home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / a_utils / c_style.lha / cstyle / cstyle.ms
Text File  |  1990-06-25  |  101KB  |  3,350 lines
  1. .\" ---------------- %snip --------------- % cut here -----------------
  2. .\"
  3. .\" Version of Indian Hill Style Manual (U of T amended)
  4. .\" revision $Revision: 6.1 $
  5. .\"
  6. .\" make with  ``... | tbl | {{di,}t,n}roff -ms ..''
  7. .\" See the `.ds C C\"' macro, to set the C source code font.
  8. .\"
  9. .\" This document was really written with `troff' in mind.  You will
  10. .\" need to do significant hacking to get nice output with `nroff'.
  11. .\"
  12. .\" You may have comments, suggestions, bug fixes, etc.  Send them to
  13. .\" me and I will try to incorporate them (one way or another) in to
  14. .\" a future version.   If you change this document, please add a note
  15. .\" that it has been modified and change the minor version number
  16. .\" (e.g., version 5.0 becomes 5.1 or 5.0.zork, or whatever) and the
  17. .\" last date of modification (printed in the footer of each page).
  18. .\"
  19. .\" pardo@cs.washington.edu or
  20. .\" {rutgers,cornell,ucsd,ubc-cs,tektronix}!uw-beaver!june!pardo
  21. .\"
  22. .\"
  23. .\"--------------------
  24. .\" Footnote numbering
  25. .ds f \\u\s-2\\n+f\\s+2\d
  26. .nr f 0 1
  27. .ds F \\n+F.
  28. .nr F 0 1
  29. .\"--------------------
  30. .\" Select a font and a format for blocks of code.
  31. .\" If your system has fixed-width fonts, then that's
  32. .\" probably what you want to use.  If your system doesn't
  33. .\" support fixed-width fonts, then use the default.
  34. .\" Really aggressive hackers will want to use vgrind (grind).
  35. .\"
  36. .ds C C\"        \" Fixed-width font.  (`.ds C CW' if no C?)
  37. .\" `Ex': start example.
  38. .de Ex
  39. .DS \\$1
  40. .ft \*C
  41. .\" .DS \\$1        \" Use w/ any fixed-width font!
  42. .\" .ft \*C        \" Use fixed-width font.
  43. .\" .ft R        \" Default font if you don't have fixed-width.
  44. .\" .vS            \" Use vgrind.  (BROKE?)
  45. ..
  46. .\"
  47. .\" `Ee': end example.
  48. .de Ee
  49. .DE
  50. .\" .vE            \" End vgrind block.
  51. .\" .DE            \" One of the fonts.
  52. ..
  53. .\" Same idea, select a font for program text appearing `inline' in
  54. .\" the text.  use the same selection choices as for code blocks.
  55. .\" Prepend `\&' in case the trailing arg starts w/ a period.
  56. .\"
  57. .\" Usage:
  58. .\"    .Ec foo         (`foo' in code font)
  59. .\"    .Ec foo mp      (`foomp', `foo' in code font, `mp' not)
  60. .\"    .Ec foo mp ka   (`kafoomp', `foo' in code font, rest not)
  61. .\"
  62. .de Ep
  63. .nh
  64. \&\\$3\c
  65. .ft \*C
  66. \\$1\fP\\$2\"            fixed-width font (not broke...)
  67. .hy
  68. .\"\&\\$3\f\*C\\$1\fP\\$2\"    fixed-width font (BUG: BROKE!)
  69. .\"\&\\$3\fC\\$1\fP\\$2\"    fixed-width font
  70. .\" \&\\$3\fB\\$1\fP\\$2\"    default (general) font
  71. ..
  72. .\"    Same idea, select a font for `ideas' (concepts) that appear
  73. .\"    in the text.
  74. .de Ec
  75. \&\\$3\fI\\$1\fP\\$2
  76. ..
  77. .\"--------------------
  78. .\"
  79. .nr x \w'    '\" find width of 4 spaces.
  80. .ta \nxu +\nxu +\nxu +\nxu +\nxu +\nxu +\nxu +\nxu +\nxu  \" set tabs using that
  81. .\"
  82. .\"--------------------
  83. .\" Long digressionary comment:  There's lots of embedded junk that
  84. .\" acts as ``rationale'' for rules or explains something or is of
  85. .\" some interest, but of limited relevance.  Those embedded comments
  86. .\" might well be interesting to somebody, thus they should PERHAPS
  87. .\" optionally be
  88. .\"
  89. .\" (a) ignored (yes!)
  90. .\" (b) printed as endnotes
  91. .\" (c) printed as footnotes
  92. .\" (d) printed as inline text
  93. .\"
  94. .\" That is,
  95. .\"
  96. .\"     mumble, foo, bar, zork.
  97. .\"     .BS
  98. .\"     The zoop machine bit-aligns the user
  99. .\"     The foop machine byte-aligns the user.
  100. .\"     The boop machine floats the user right out the door.
  101. .\"     .ES
  102. .\"     Other sterling words of wisdom.
  103. .\"
  104. .\" So suppose that register `r' and macro/string `ZZ' are unused,
  105. .\" then reasonable macros include:
  106. .\"
  107. .\"     .de BS
  108. .\"     .if \\nr==0 .de ZZ ES
  109. .\"     .if \\nr==1 .BE
  110. .\"     .if \\nr==2 .FS
  111. .\"     ..
  112. .\"     .de ES
  113. .\"     .if \\nr==1 .EE
  114. .\"     .if \\nr==2 .FE
  115. .\"     ..
  116. .\"
  117. .\" Then, if register r is 0, everything from the .BS to the .ES will
  118. .\" become the definition of a macro ZZ, which are never read back;
  119. .\" thus it is effectively (and fairly efficiently) thrown away.
  120. .\"
  121. .\" If register r is 1, .BS invokes .BE, and .ES invokes .EE --
  122. .\" supposing .BE and .EE are names for macros for end-notes, though
  123. .\" such thing might not exist in the -ms macros.  IMHO, the various
  124. .\" comments shouldn't be end-nodes.  End-notes are for things like
  125. .\" "op. cit. pp. 6-42", never for actual commentary on the text; it's
  126. .\" just too much effort to read them.
  127. .\"
  128. .\" If register r is 2, .BS invokes .FS, and .ES invokes .FE; and
  129. .\" if register r has any other value, .BE and .ES do nothing at all,
  130. .\" so the material comes out inline.  (The text should probably be
  131. .\" blocked out with a `.QP' and a `\fBRemark:\fP or some such; see
  132. .\" Knuth's "dangerous bend" paragraphs in The TeXBook.)
  133. .\"
  134. .\" Using a register with a 1-character name because it works nicely
  135. .\" with troff's -r option.  With the above macros, doing nothing
  136. .\" makes the optional comments to disappear, -rr1 makes them in to
  137. .\" end-notes, -rr2 for footnotes, and -rr3 for inline text.
  138. .\"
  139. .\" It probably isn't a good idea to do all that, though.  People will
  140. .\" just get confused about versions.  Better to just include or
  141. .\" exclude the notes.
  142. .\"
  143. .\"----------------
  144. .RP
  145. .TL
  146. Recommended C Style and Coding Standards
  147. .AU
  148. L.W. Cannon
  149. R.A. Elliott
  150. L.W. Kirchhoff
  151. J.H. Miller
  152. J.M. Milner
  153. R.W. Mitze
  154. E.P. Schan
  155. N.O. Whittington
  156. .AI
  157. Bell Labs
  158. .AU
  159. Henry Spencer
  160. .AI
  161. Zoology Computer Systems
  162. University of Toronto
  163. .AU
  164. David Keppel
  165. .AI
  166. EECS, UC Berkeley
  167. CS&E, University of Washington
  168. .AU
  169. Mark Brader
  170. .AI
  171. SoftQuad Incorporated
  172. Toronto
  173. .AB
  174. This document is an updated version of the
  175. \fIIndian Hill C Style and Coding Standards\fP
  176. paper,
  177. with modifications by the last three authors.
  178. It describes a recommended coding standard for
  179. C
  180. programs.
  181. The scope is coding style, not functional organization.
  182. .AE
  183. .\"--------------------
  184. .\" Headers/footers must be in double quotes because most versions
  185. .\" of .OF, .OH, ... are BROKE.  (They work until you get 10 arguments
  186. .\" and then silently truncate...
  187. .\" revision $Revision: 6.1 $
  188. .\"
  189. .OF "'Recommended C Coding Standards'Revision: 6.0'25 June 1990'"
  190. .EF "'Recommended C Coding Standards'Revision: 6.0'25 June 1990'"
  191. .nr PO 1.25i
  192. .ta 0.5i 1.0i 1.5i 2.0i 2.5i 3.0i
  193. .\"--------------------
  194. .NH
  195. Introduction
  196. .PP
  197. This document
  198. is a modified version of a document from
  199. a committee formed at AT&T's Indian Hill labs to establish
  200. a common set of coding standards and recommendations for the
  201. Indian Hill community.
  202. .\"
  203. .\" old:
  204. .\"
  205. .\" The scope of this work is C coding style,
  206. .\" rather than the functional organization of programs
  207. .\" or general issues such as the use of \fIgoto\fPs.
  208. .\"
  209. The scope of this work is C coding style.
  210. Good style should encourage consistent layout, improve
  211. portability, and reduce errors.
  212. .\"
  213. .\" "It's simply a matter of style, and while there
  214. .\" are many wrong styles, there really isn't any
  215. .\" one right style."      -- Ray Butterworth
  216. .\"
  217. This work does not cover functional organization, or general
  218. issues such as the use of
  219. .Ec goto s.
  220. We\*f
  221. .FS
  222. .IP \*F
  223. The opinions in this document
  224. do not reflect the opinions of all authors.
  225. This is still an evolving document.
  226. Please send comments and suggestions to
  227. pardo@cs.washington.edu or
  228. {rutgers,cornell,ucsd,ubc-cs,tektronix}!uw-beaver!june!pardo
  229. .FE
  230. have tried to combine previous work [1,6,8] on C style into a uniform
  231. set of standards that should be appropriate for any project using C,
  232. although parts are biased towards particular systems.
  233. Of necessity, these standards cannot cover all situations.
  234. Experience and informed judgement count for much.
  235. Programmers who encounter unusual situations should
  236. consult either
  237. experienced C programmers or code written by experienced C
  238. programmers (preferably following these rules).
  239. .PP
  240. The standards in this document are not of themselves required, but
  241. individual institutions or groups may adopt part or all of them
  242. as a part of program acceptance.
  243. It is therefore likely that others at your institution will code in
  244. a similar style.
  245. Ultimately, the goal of these standards is to
  246. increase portability, reduce maintenance, and above all
  247. improve clarity.
  248. .PP
  249. Many of the style choices here are somewhat arbitrary.
  250. Mixed coding style is harder to maintain than bad coding style.
  251. When changing existing code it is better to conform to the
  252. style (indentation, spacing, commenting, naming conventions)
  253. of the existing code than it is to blindly follow this document.
  254. .QP
  255. ``\fITo be clear is professional; not to be clear
  256. is unprofessional.\fP'' \(em Sir Ernest Gowers.
  257. .NH
  258. File Organization
  259. .PP
  260. A file consists of various sections that should be separated by
  261. several blank lines.
  262. Although there is no maximum length limit for source files,
  263. files with more than about 1000 lines are cumbersome to deal with.
  264. The editor may not have enough temp space to edit the file,
  265. compilations will go more slowly,
  266. etc.
  267. Many rows of asterisks, for example,
  268. present little information compared to the time it takes to scroll past,
  269. and are discouraged.
  270. Lines longer than 79 columns are not handled well by all terminals
  271. and should be avoided if possible.
  272. Excessively long lines which result from deep indenting are often
  273. a symptom of poorly-organized code.
  274. .NH 2
  275. File Naming Conventions
  276. .PP
  277. File names are made up of a base name,
  278. and an optional period and suffix.
  279. The first character of the name should be a letter
  280. and all characters (except the period)
  281. should be lower-case letters and numbers.
  282. The base name should be eight or fewer characters and the
  283. suffix should be three or fewer characters
  284. (four, if you include the period).
  285. These rules apply to both program files and
  286. default files used and produced by the program
  287. (e.g., ``rogue.sav'').
  288. .\"
  289. .\" 8 + 1 + 3 + ",v" fits RCS into Version 7 filesystems.
  290. .\" MS-DOS does 8 + "." + 3.
  291. .\"
  292. .PP
  293. Some compilers and tools require certain suffix conventions for names
  294. of files [5].
  295. The following suffixes are required:
  296. .IP \0\0\(bu
  297. C source file names must end in \fI.c\fP
  298. .IP \0\0\(bu
  299. Assembler source file names must end in \fI.s\fP
  300. .LP
  301. The following conventions are universally followed:
  302. .IP \0\0\(bu
  303. Relocatable object file names end in \fI.o\fP
  304. .IP \0\0\(bu
  305. Include header file names end in \fI.h\fP.
  306. .\"
  307. .\" \*f.
  308. .\" .FS
  309. .\" .IP \*F
  310. .\"
  311. An alternate convention that may
  312. be preferable in multi-language environments
  313. is to suffix both the language type and \fI.h\fP
  314. (e.g. ``foo.c.h'' or ``foo.ch'').
  315. .FE
  316. .IP \0\0\(bu
  317. Yacc source file names end in \fI.y\fP
  318. .IP \0\0\(bu
  319. Lex source file names end in \fI.l\fP
  320. .PP
  321. C++ has compiler-dependent suffix conventions,
  322. including \fI.c\fP, \fI..c\fP, \fI.cc\fP, \fI.c.c\fP, and \fI.C\fP.
  323. Since much C code is also C++ code, there is no clear solution here.
  324. .PP
  325. In addition,
  326. it is conventional to use ``Makefile'' (not ``makefile'') for the
  327. control file for \fImake\fP (for systems that support it)
  328. and ``README'' for a summary of the contents
  329. of the directory or directory tree.
  330. .\"
  331. .\" Having ``README'' in caps breaks the "monocase" rule, but is
  332. .\" convention.  Same for ``Makefile''.
  333. .\"
  334. .NH 2
  335. Program Files
  336. .PP
  337. The suggested order of sections for a program file is as follows:
  338. .IP 1.
  339. First in the file is a prologue that tells what is in that file.
  340. A description of the purpose of the objects in the files (whether
  341. they be functions, external data declarations or definitions, or
  342. something else) is more useful than a list of the object names.
  343. The prologue may optionally contain author(s),
  344. revision control information, references, etc.
  345. .IP 2.
  346. Any header file includes should be next.
  347. If the include is for a non-obvious reason,
  348. the reason should be commented.
  349. In most cases, system include files like \fIstdio.h\fP should be
  350. included before user include files.
  351. .IP 3.
  352. Any defines and typedefs that apply to the file as a whole are next.
  353. One normal order is to have
  354. ``constant'' macros first,
  355. then ``function'' macros, then typedefs and enums.
  356. .IP 4.
  357. Next come the global (external) data declarations,
  358. usually in the order: externs, non-static globals, static globals.
  359. If a set of defines applies to a particular piece of global data
  360. (such as a flags word), the defines should be immediately after
  361. the data declaration or embedded in structure declarations,
  362. indented to put the defines one level
  363. deeper than the first keyword of the declaration to which they apply.
  364. .IP 5.
  365. The functions come last,
  366. and should be in some sort of meaningful order.
  367. Like functions should appear together.
  368. A ``breadth-first''
  369. approach (functions on a similar level of abstraction together) is
  370. preferred over depth-first (functions defined as soon as possible
  371. before or after their calls).
  372. Considerable judgement is called for here.
  373. If defining large numbers of essentially-independent utility
  374. functions, consider alphabetical order.
  375. .NH 2
  376. Header Files
  377. .PP
  378. Header files are files that are included in other files prior to
  379. compilation by the C preprocessor.
  380. Some, such as \fIstdio.h\fP, are defined at the system level
  381. and must included by any program using the standard I/O library.
  382. Header files are also used to contain data declarations and defines
  383. that are needed by more than one program.
  384. Header files should be functionally organized,
  385. i.e., declarations for separate subsystems
  386. should be in separate header files.
  387. Also, if a set of declarations is likely to change when code is
  388. ported from one machine to another, those declarations should be
  389. in a separate header file.
  390. .PP
  391. Avoid private header filenames that are the same
  392. as library header filenames.
  393. The statement
  394. .Ep #include
  395. .Ep """math.h"""
  396. .\"
  397. .\" Or try .Ep math.h """" """"
  398. .\"
  399. will include the standard library math header file
  400. if the intended one is not
  401. found in the current directory.
  402. If this is what you \fIwant\fP to happen,
  403. comment this fact.
  404. Don't use absolute pathnames for header files.
  405. Use the
  406. .Ec <name>
  407. construction for getting them from a standard
  408. place, or define them relative to the current directory.
  409. The ``include-path'' option of the C compiler
  410. (\-I on many systems)
  411. is the best way to handle
  412. extensive private libraries of header files;  it permits reorganizing
  413. the directory structure without having to alter source files.
  414. .PP
  415. Header files that declare functions or external variables should be
  416. included in the file that defines the function or variable.
  417. That way, the compiler can do type checking and the external
  418. declaration will always agree with the definition.
  419. .PP
  420. Defining variables in a header file is often a poor idea.
  421. Frequently it is a symptom of poor partitioning of code between files.
  422. Also, some objects like typedefs and initialized data definitions
  423. cannot be seen twice by the compiler in one compilation.
  424. On some systems, repeating uninitialized declarations
  425. without the \fIextern\fP keyword also causes problems.
  426. Repeated declarations can happen if include files are nested
  427. and will cause the compilation to fail.
  428. .PP
  429. Header files should not be nested.
  430. .\"
  431. .\" Many people disagree strongly with this.
  432. .\" However, if you are to use \fIone\fP style, then this is best.
  433. .\" The #ifndef/#define/.../#endif approach (below) often causes
  434. .\" compilations to go much slower.
  435. .\" A #endinput directive would be nice.
  436. .\"
  437. The prologue for a header file should, therefore, describe what
  438. other headers need to be #included for the header to be functional.
  439. In extreme cases, where a large number of header files are to be
  440. included in several different source files,
  441. it is acceptable to put all common #includes in one include file.
  442. .PP
  443. It is common to put the following into each
  444. .Ec .h
  445. file
  446. to prevent accidental double-inclusion.
  447. .Ex
  448. #ifndef EXAMPLE_H
  449. #define EXAMPLE_H
  450. \&...    \fI/* body of example.h file */\fP
  451. #endif /* EXAMPLE_H */
  452. .Ee
  453. .LP
  454. This double-inclusion mechanism should not be relied upon,
  455. particularly to perform nested includes.
  456. .NH 2
  457. Other Files
  458. .PP
  459. It is conventional to have a file called ``README'' to document both
  460. ``the bigger picture'' and issues for the program as a whole.
  461. For example, it is common to include a list of all conditional
  462. compilation flags and what they mean.
  463. It is also common to list files that are machine dependent, etc.
  464. .NH
  465. Comments
  466. .QP
  467. .ad r
  468. ``\fIWhen the code and the comments disagree,
  469. both are probably wrong.\fP'' \(em Norm Schryer
  470. .\" \fIBumper-Sticker Computer Science\fP,
  471. .\" Jon Bently's \fIProgramming Pearls\fP column,
  472. .\" Communications of the ACM (CACM),
  473. .\" September 1985, Volume 28, Number 9.
  474. .\"
  475. .\" ``\fIMany's the time when I've thanked the Doug A. Gwyn of past
  476. .\" years for anticipating future maintenance questions and providing
  477. .\" helpful information in the original sources.\fP'' \(em Doug A.
  478. .\" Gwyn
  479. .\"
  480. .br
  481. .ad b
  482. .PP
  483. The comments should describe \fIwhat\fP is happening,
  484. \fIhow\fP it is being done,
  485. what parameters mean,
  486. .\"
  487. .\" BUG:
  488. .\" By X3.159-1989, ``formal parameters'' are called `parameters' and
  489. .\" ``actual parameters'' are called `arguments'.  A somewhat relaxed
  490. .\" form lets us call anything an argument, but only some formal
  491. .\" parameters are `parameters'.
  492. .\" The two usages are used inconsistantly in this document.
  493. .\"
  494. which globals are used and which are modified,
  495. and any restrictions or bugs.
  496. Avoid, however, comments that are clear from the code,
  497. as such information rapidly gets out of date.
  498. Comments that disagree with the code are of negative value.
  499. Short comments should be
  500. \fIwhat\fP comments, such as ``compute mean value'',
  501. rather than \fIhow\fP comments such as
  502. ``sum of values divided by n''.
  503. C is not assembler;
  504. putting a comment at the top of a 3\-10 line section telling what it
  505. does overall is often more useful than a comment on each line
  506. describing micrologic.
  507. .PP
  508. Comments should justify offensive code.
  509. The justification should be that something bad will happen if
  510. unoffensive code is used.
  511. Just making code faster is not enough to rationalize a hack;
  512. the performance must be \fIshown\fP to be unacceptable
  513. without the hack.
  514. The comment should explain the unacceptable behavior and describe why
  515. the hack is a ``good'' fix.
  516. .PP
  517. Comments that describe data structures, algorithms, etc., should be
  518. in block comment form with the opening
  519. .Ep /*
  520. in columns 1-2, a
  521. .Ep *
  522. in column 2 before each line of comment text,
  523. and the closing
  524. .Ep */
  525. in columns 2-3.
  526. An alternative is to have
  527. .Ep **
  528. in columns 1-2, and put the closing
  529. .Ep */
  530. also in 1-2.
  531. .Ex L
  532. /*
  533.  *    Here is a block comment.
  534.  *    The comment text should be tabbed or spaced over uniformly.
  535.  *    The opening slash-star and closing star-slash are alone on a line.
  536.  */
  537. .Ee
  538. .Ex L
  539. /*
  540. ** Alternate format for block comments
  541. */
  542. .Ee
  543. .PP
  544. Note that \fIgrep '^.\e*'\fP will catch all block comments in the
  545. file\*f.
  546. .FS
  547. .IP \*F
  548. Some automated program-analysis
  549. packages use different characters before comment lines as
  550. a marker for lines with specific items of information.
  551. In particular, a line with a
  552. .Ep \- ' `
  553. in a comment preceding a function
  554. is sometimes assumed to be a one-line summary of the function's
  555. purpose.
  556. .FE
  557. Very long block comments such as drawn-out discussions and copyright
  558. notices often start with
  559. .Ep /*
  560. in columns 1-2, no leading
  561. .Ep *
  562. before lines of text, and the closing
  563. .Ep */
  564. in columns 1-2.
  565. Block comments inside a function are appropriate, and
  566. they should be tabbed over to the same tab setting as the code that
  567. they describe.
  568. One-line comments alone on a line should be indented to the tab
  569. setting of the code that follows.
  570. .Ex
  571. if (argc > 1) {
  572.     /* Get input file from command line. */
  573.     if (freopen(argv[1], "r", stdin) =\^= NULL) {
  574.         perror (argv[1]);
  575.     }
  576. }
  577. .Ee
  578. .PP
  579. Very short comments may appear on the same line as the code they
  580. describe,
  581. and should be tabbed over to separate them from the statements.
  582. If more than one short comment appears in a block of code
  583. they should all be tabbed to the same tab setting.
  584. .Ex
  585. if (a =\^= EXCEPTION) {
  586.     b = TRUE;                /* special case */
  587. } else {
  588.     b = isprime(a);            /* works only for odd a */
  589. }
  590. .Ee
  591. .NH
  592. Declarations
  593. .PP
  594. Global declarations should begin in column 1.
  595. All external data declaration should be preceded by the
  596. .Ec extern
  597. keyword.
  598. If an external variable is an array that is defined with an explicit
  599. size, then the array bounds must be repeated in the extern
  600. declaration unless the size is always encoded in the array
  601. (e.g., a read-only character array that is always null-terminated).
  602. Repeated size declarations are
  603. particularly beneficial to someone picking up code written by another.
  604. .\"
  605. .\" /* foo.h */
  606. .\" #define SIZE 1234
  607. .\" extern int zork[SIZE];    /* ... and not `extern int zork[];' */
  608. .\"
  609. .\" /* foo.c */
  610. .\" int zork[SIZE];
  611. .\"
  612. .PP
  613. The ``pointer'' qualifier,
  614. .Ep * ', `
  615. should be with the variable name rather
  616. than with the type.
  617. .Ex
  618. char        *s, *t, *u;
  619. .Ee
  620. instead of
  621. .Ex
  622. char*    s, t, u;
  623. .Ee
  624. which is wrong, since
  625. .Ep t ' `
  626. and
  627. .Ep u ' `
  628. do not get declared as pointers.
  629. .PP
  630. Unrelated declarations, even of the same type,
  631. should be on separate lines.
  632. A comment describing the role of the object being declared should be
  633. included, with the exception
  634. that a list of
  635. .Ec #define d
  636. constants do not need comments
  637. if the constant names are sufficient documentation.
  638. The names, values, and comments
  639. are usually
  640. .\" should be
  641. tabbed so that they line up underneath each other.
  642. Use the tab character rather than blanks (spaces).
  643. For structure and union template declarations,
  644. each element should be alone on a line
  645. with a comment describing it.
  646. The opening brace
  647. .Ep { \^\^) (\^
  648. should be on the same line as the structure
  649. tag, and the closing brace
  650. .Ep } \^) (\^\^
  651. should be in column 1.
  652. .Ex
  653. struct boat {
  654.     int        wllength;    /* water line length in meters */
  655.     int        type;        /* see below */
  656.     long        sailarea;    /* sail area in square mm */
  657. };
  658.  
  659. /* defines for boat.type */
  660. #define    KETCH    (1)
  661. #define    YAWL        (2)
  662. #define    SLOOP    (3)
  663. #define    SQRIG    (4)
  664. #define    MOTOR    (5)
  665. .Ee
  666. .\"
  667. .\" If this formatting `loses', you can probably fix it, but you'll
  668. .\" have to be careful about tabs that appear later.
  669. .\"
  670. .\" .\" Set up a tab field, with the worst-case tabbing, more or less
  671. .\" .ta \w'MOTOR    'u
  672. .\" .\" #define KETCH<tab>1 (etc.)
  673. .\"
  674. .LP
  675. These defines are sometimes put right after the declaration of
  676. .Ep type ,
  677. within the
  678. .Ep struct
  679. declaration, with enough tabs after the
  680. .Ep # \^' `
  681. to indent
  682. .Ep define
  683. one level more than the structure member declarations.
  684. When the actual values are unimportant,
  685. the
  686. .Ec enum
  687. facility is better\*f.
  688. .FS
  689. .IP \*F
  690. .Ec enum s
  691. might be better anyway.
  692. .FE
  693. .Ex
  694. enum bt { KETCH=1, YAWL, SLOOP, SQRIG, MOTOR };
  695. struct boat {
  696.     int        wllength;    /* water line length in meters */
  697.     enum bt    type;        /* what kind of boat */
  698.     long        sailarea;    /* sail area in square mm */
  699. };
  700. .Ee
  701. .PP
  702. Any variable whose initial value is important should be
  703. \fIexplicitly\fP initialized, or at the very least should be commented
  704. to indicate that C's default initialization to zero
  705. is being relied upon.
  706. The empty initializer,
  707. .Ep {\^} '', ``
  708. should never be used.
  709. Structure
  710. initializations should be fully parenthesized with braces.
  711. .\"
  712. .\" Consider the following:
  713. .\"
  714. .\" struct foo {int i, j};
  715. .\" struct foo bar[] = {1, 2, 3, 4};
  716. .\" struct foo kung[] = {{1, 2}, {3, 4}};
  717. .\" struct foo oh[] = {};
  718. .\"
  719. .\" `bar' is accepted, but is visually ambiguous.
  720. .\" `oh' is also accepted.  Don't do it -- what does it mean?
  721. .\"
  722. .\" The following is NOT ambiguous and is good style.
  723. .\"
  724. .\" struct foo kung[] = {{1}, {3}};
  725. .\"
  726. Constants used to initialize longs should be explicitly long.
  727. Use capital letters; for example two long
  728. .Ep 2l '' ``
  729. looks a lot like
  730. .Ep 21 '', ``
  731. the number twenty-one.
  732. .Ex
  733. int        x = 1;
  734. char        *msg = "message";
  735. struct boat    winner[] = {
  736.     { 40, YAWL, 6000000L },
  737.     { 28, MOTOR, 0L },
  738.     { 0 },
  739. };
  740. .Ee
  741. .PP
  742. In any file which is part of a larger whole rather than a self-contained
  743. program, maximum use should be made of the
  744. .Ec static
  745. keyword to make functions and variables local to single files.
  746. Variables in particular should be accessible from other files
  747. only when there is a clear
  748. need that cannot be filled in another way.
  749. Such usage should be commented to make it clear that another file's
  750. variables are being used; the comment should name the other file.
  751. If your debugger hides static objects you need to see during
  752. debugging,
  753. declare them as
  754. .Ep STATIC
  755. and #define
  756. .Ep STATIC
  757. as needed.
  758. .PP
  759. The most important types should be highlighted by typedeffing
  760. them, even if they are only integers,
  761. as the unique name makes the program easier to read (as long as there
  762. are only a \fIfew\fP things typedeffed to integers!).
  763. Structures may be typedeffed when they are declared.
  764. Give the struct and the typedef the same name.
  765. .Ex
  766. typedef struct splodge_t {
  767.     int    sp_count;
  768.     char    *sp_name, *sp_alias;
  769. } splodge_t;
  770. .Ee
  771. .PP
  772. The return type of functions should always be declared.
  773. If function prototypes are available, use them.
  774. One common mistake is to omit the
  775. declaration of external math functions that return
  776. .Ec double .
  777. The compiler then assumes that
  778. the return value is an integer and the bits are dutifully
  779. converted into a (meaningless) floating point value.
  780. .QP
  781. .ce
  782. ``\fIC takes the point of view that the programmer is always right.\fP'' \(em Michael DeCorte
  783. .NH
  784. Function Declarations
  785. .PP
  786. Each function should be preceded by a block comment prologue
  787. that gives a short description of what the function does
  788. and (if not clear) how to use it.
  789. Discussion of non-trivial design decisions and
  790. side-effects is also appropriate.
  791. Avoid duplicating information clear from the code.
  792. .PP
  793. The function return type should be alone on a line,
  794. (optionally) indented one stop\*f.
  795. .FS
  796. .IP \*F
  797. ``Tabstops'' can be blanks (spaces) inserted by your editor in clumps
  798. of 2, 4, or 8.
  799. Use actual tabs where possible.
  800. .FE
  801. Do not default to
  802. .Ec int ;
  803. if the function does not return a value then it should be given
  804. return type \fIvoid\fP\*f.
  805. .FS
  806. .IP \*F
  807. .Ep "#define"
  808. .Ep void
  809. or
  810. .Ep "#define"
  811. .Ep void
  812. .Ep int
  813. for compilers without the
  814. .Ec void
  815. keyword.
  816. .FE
  817. If the value returned requires a long explanation,
  818. it should be given in the prologue;
  819. otherwise it can be on the same line as the return type, tabbed over.
  820. The function name
  821. (and the formal parameter list)
  822. should be alone on a line, in column 1.
  823. Destination (return value) parameters
  824. should generally be first (on the left).
  825. All formal parameter declarations,
  826. local declarations and code within the function body
  827. should be tabbed over one stop.
  828. The opening brace of the function body should be alone on a line
  829. beginning in column 1.
  830. .PP
  831. Each parameter should be declared (do not default to
  832. .Ec int ).
  833. In general the role of each variable in the function should be described.
  834. This may either be done in the function comment or, if each declaration
  835. is on its own line, in a comment on that line.
  836. Loop counters called ``i'',  string pointers called ``s'',
  837. and integral types called ``c'' and used for characters
  838. are typically excluded.
  839. If a group of functions all have a like parameter or local variable,
  840. it helps to call the repeated variable by the same name in all
  841. functions.
  842. (Conversely, avoid using the same name for different purposes in
  843. related functions.)
  844. Like parameters should also appear in the same place in the various
  845. argument lists.
  846. .PP
  847. Comments for parameters and local variables should be
  848. tabbed so that they line up underneath each other.
  849. Local variable declarations should be separated
  850. from the function's statements by a blank line.
  851. .\"
  852. .\"    int zork;            /* Last known zork. */
  853. .\"    struct price_tag inventory[MAX_STORES][MAX_STOCK]
  854. .\"                    /* Corporate structure. */
  855. .\"    some_really_long_type_name *tree;
  856. .\"                    /* root of the parse tree */
  857. .\"    char *s;            /* variable name */
  858. .\"
  859. .\" If a variable has an extremely long definition, the comment
  860. .\" should come \fIafter\fP the declaration.  Multiline comments
  861. .\" for variables should be moved to the header and referenced
  862. .\" from the comment.
  863. .\"
  864. .\"    * Note 1: The variable `zork' has two lives.  It first ...
  865. .\"    */
  866. .\"
  867. .\"        void *zork;        /* See header note #1. */
  868. .\"
  869. .PP
  870. Be careful when you use or declare functions
  871. that take a variable number of arguments (``varargs'').
  872. There is no truly portable way to do varargs in C.
  873. Better to design an interface that uses a fixed number of arguments.
  874. If you must have varargs,
  875. use the library macros for declaring functions with
  876. variant argument lists.
  877. .PP
  878. If the function uses any external variables (or functions)
  879. that are not declared globally in the file,
  880. these should have their
  881. own declarations in the function body using the
  882. .Ec extern
  883. keyword.
  884. .PP
  885. Avoid local declarations that override declarations at higher levels.
  886. In particular, local variables
  887. should not be redeclared in nested blocks.
  888. Although this is valid C, the potential confusion is
  889. enough that
  890. \fIlint\fP will complain about it when given the \-h option.
  891. .NH
  892. Whitespace
  893. .QP
  894. .ad r
  895. \fIint i;main(){for(;i["]<i;++i){--i;}"];read('-'-'-',i+++"hell\\
  896. .br
  897. o, world!\\n",'/'/'/'));}read(j,i,p){write(j/p+p,i---j,i/i);}\fP
  898. .br
  899. \(em Dishonorable mention, Obfuscated C Code Contest, 1984.
  900. .br
  901. Author requested anonymity.
  902. .br
  903. .ad b
  904. .PP
  905. .\"Use whitespace generously, both vertically and horizontally.
  906. Use vertical and horizontal whitespace generously.
  907. Indentation and spacing should reflect the block structure of the code;
  908. e.g.,
  909. there should be at least 2 blank lines between the end of one function
  910. and the comments for the next.
  911. .PP
  912. A long string of conditional operators should be split
  913. onto separate lines.
  914. .Ex
  915. if (foo->next=\^=NULL && totalcount<needed && needed<=MAX_ALLOT
  916.     && server_active(current_input)) { ...
  917. .Ee
  918. Might be better as
  919. .Ex
  920. if (foo->next =\^= NULL
  921.     && totalcount < needed && needed <= MAX_ALLOT
  922.     && server_active(current_input))
  923. {
  924.     ...
  925. .Ee
  926. Similarly, elaborate
  927. .Ec for
  928. loops should be split onto different lines.
  929. .Ex
  930. for (curr = *listp, trail = listp;
  931.     curr != NULL;
  932.     trail = &(curr->next), curr = curr->next )
  933. {
  934. \&    ...
  935. .Ee
  936. Other complex expressions, particularly those using the ternary
  937. .Ec ?\^:
  938. operator,
  939. are best split on to several lines, too.
  940. .Ex
  941. c = (a == b)
  942.     ? d + f(a)
  943.     : f(b) - d;
  944. .Ee
  945. .\" .PP
  946. .\" Finally, the closing brace of long functions and very long blocks
  947. .\" should include an ``end function'' or ``end block'' comment:
  948. .\" .DS
  949. .\" \&    }    /* end  for (each list element) */
  950. .\" \&    ...
  951. .\" }    /* end function_name() */
  952. .Ee
  953. Keywords that are followed by expressions in parentheses
  954. should be separated from the left parenthesis by a blank.
  955. (The
  956. .Ec sizeof
  957. operator is an exception.)
  958. .\"
  959. .\" Because `sizeof' is an OPERATOR.
  960. .\"
  961. Blanks should also appear after commas in argument lists to help
  962. separate the arguments visually.
  963. On the other hand, macro definitions with arguments must
  964. not have a blank between the name and the left parenthesis,
  965. otherwise the C preprocessor will not recognize the argument list.
  966. .\"
  967. .\" The C preprocessor requires the left parenthesis,
  968. .\" to be immediately after the macro name or else the argument list
  969. .\" will not be recognized.
  970. .\"
  971. .NH
  972. Examples
  973. .\"
  974. .\" Perhaps this should be a complete file?
  975. .\"
  976. .PP
  977. .Ex
  978. /*
  979.  *    Determine if the sky is blue by checking that it isn't night.
  980.  *    CAVEAT: Only sometimes right.  May return TRUE when the answer
  981.  *    is FALSE.  Consider clouds, eclipses, short days.
  982.  *    NOTE: Uses `hour' from `hightime.c'.  Returns `int' for
  983.  *    compatibility with the old version.
  984.  */
  985.     int                        /* true or false */
  986. skyblue()
  987. {
  988.     extern int    hour;        /* current hour of the day */
  989.  
  990.     return (hour >= MORNING && hour <= EVENING);
  991. }
  992. .Ee
  993. .Ex
  994. /*
  995.  *    Find the last element in the linked list
  996.  *    pointed to by nodep and return a pointer to it.
  997.  *    Return NULL if there is no last element.
  998.  */
  999.     node_t *
  1000. tail(nodep)
  1001.     node_t    *nodep;            /* pointer to head of list */
  1002. {
  1003.     register node_t    *np;        /* advances to NULL */
  1004.     register node_t    *lp;        /* follows one behind np */
  1005.  
  1006.     if (nodep =\^= NULL)
  1007.         return (NULL);
  1008.     for (np = lp = nodep; np != NULL; lp = np, np = np->next)
  1009.         ;    /* VOID */
  1010.     return (lp);
  1011. }
  1012. .Ee
  1013. .NH
  1014. Simple Statements
  1015. .PP
  1016. There should be only one statement per line unless the statements are
  1017. very closely related.
  1018. .Ex
  1019. case FOO:      oogle (zork);  boogle (zork);  break;
  1020. case BAR:      oogle (bork);  boogle (zork);  break;
  1021. case BAZ:      oogle (gork);  boogle (bork);  break;
  1022. .Ee
  1023. The null body of a
  1024. .Ec for
  1025. or
  1026. .Ec while
  1027. loop should be alone on a line and commented
  1028. so that it is clear that the null body is intentional
  1029. and not missing code.
  1030. .Ex
  1031. while (*dest++ = *src++)
  1032.     ;    /* VOID */
  1033. .Ee
  1034. .\"
  1035. .\" An alternative convention is to use
  1036. .\" .Ep continue
  1037. .\" explicitly.
  1038. .\" .Ex
  1039. .\" while (*dest++ = *src++)
  1040. .\"    continue;
  1041. .\" .Ee
  1042. .\"
  1043. .PP
  1044. Do not default the test for non-zero, i.e.
  1045. .Ex
  1046. if (f(\^) != FAIL)
  1047. .Ee
  1048. is better than
  1049. .Ex
  1050. if (f(\^))
  1051. .Ee
  1052. even though
  1053. .Ep FAIL
  1054. may have the value 0 which C considers to be false.
  1055. An explicit test will help you out later when somebody decides that a
  1056. failure return should be \-1 instead of 0.
  1057. Explicit comparison should be used even if the comparison value will
  1058. never change; e.g., 
  1059. .Ep "if (!(bufsize % sizeof(int)))" '' ``
  1060. should be written instead as
  1061. .Ep "if ((bufsize % sizeof(int)) =\^= 0)" '' ``
  1062. to reflect the \fInumeric\fP (not \fIboolean\fP) nature of the test.
  1063. A frequent trouble spot is using
  1064. .Ep strcmp
  1065. to test for string equality, where the result should \fInever\fP
  1066. \fIever\fP be defaulted.
  1067. The preferred approach is to define a macro \fISTREQ\fP.
  1068. .Ex
  1069. #define STREQ(a, b) (strcmp((a), (b)) =\^= 0)
  1070. .Ee
  1071. .PP
  1072. The non-zero test \fIis\fP often defaulted for predicates
  1073. and other functions or expressions which meet the following
  1074. restrictions:
  1075. .IP \0\0\(bu
  1076. Evaluates to 0 for false, nothing else.
  1077. .IP \0\0\(bu
  1078. Is named so that the meaning of (say) a `true' return
  1079. is absolutely obvious.
  1080. Call a predicate \fIisvalid\fP or \fIvalid\fP, not \fIcheckvalid\fP.
  1081. .\"
  1082. .\" The non-zero test is also defaulted for NULL pointer checks,
  1083. .\" e.g.,
  1084. .\" .Ep "p = malloc(n); if (!p) error()" ''. ``
  1085. .\" It is defaulted because essentually you are saying ``allocate `p'.
  1086. .\" If no `p', then error.''
  1087. .\" (Thus, it is covered by the existing rules.)
  1088. .\"
  1089. .PP
  1090. It is common practice to declare a boolean type
  1091. .Ep bool '' ``
  1092. in a global include file.
  1093. .\"
  1094. .\" Unfortunately, the ideal type to use may differ for scalar and
  1095. .\" array variables.
  1096. .\"
  1097. The special names improve readability immensely.
  1098. .Ex
  1099. typedef int    bool;
  1100. #define FALSE    0
  1101. #define TRUE    1
  1102. .Ee
  1103. or
  1104. .Ex
  1105. typedef enum { NO=0, YES } bool;
  1106. .Ee
  1107. .LP
  1108. Even with these declarations,
  1109. do not check a boolean value for equality with 1 (TRUE, YES, etc.);
  1110. instead test for inequality with 0 (FALSE, NO, etc.).
  1111. Most functions are guaranteed to return 0 if false,
  1112. but only non-zero if true.
  1113. Thus,
  1114. .Ex
  1115. if (func() =\^= TRUE) { ...
  1116. .Ee
  1117. must be written
  1118. .Ex
  1119. if (func() != FALSE) { ...
  1120. .Ee
  1121. It is even better (where possible) to rename the function/variable or
  1122. rewrite the expression so that the meaning is obvious without a
  1123. comparison to true or false
  1124. (e.g., rename to \fIisvalid()\fP).
  1125. .PP
  1126. There is a time and a place for embedded assignment statements.
  1127. In some constructs there is no better way to accomplish the results
  1128. without making the code bulkier and less readable.
  1129. .Ex
  1130. while ((c = getchar()) != EOF) {
  1131.     process the character
  1132. }
  1133. .Ee
  1134. The
  1135. .Ep ++
  1136. and
  1137. .Ep \-\^\^\-
  1138. operators count as assignment statements.
  1139. So, for many purposes, do functions with side effects.
  1140. Using embedded assignment statements to improve run-time performance
  1141. is also possible.
  1142. However, one should consider the tradeoff between increased speed and
  1143. decreased maintainability that results when embedded assignments are
  1144. used in artificial places.
  1145. For example,
  1146. .Ex
  1147. a = b + c;
  1148. d = a + r;
  1149. .Ee
  1150. should not be replaced by
  1151. .Ex
  1152. d = (a = b + c) + r;
  1153. .Ee
  1154. even though the latter may save one cycle.
  1155. In the long run the time difference between the two will
  1156. decrease as the optimizer gains maturity, while the difference in
  1157. ease of maintenance will increase as the human memory of what's
  1158. going on in the latter piece of code begins to fade.
  1159. .PP
  1160. Goto statements should be used sparingly, as in any well-structured
  1161. code.
  1162. The main place where they can be usefully employed is to break out
  1163. of several levels of
  1164. .Ec switch ,
  1165. .Ec for ,
  1166. and
  1167. .Ec while
  1168. nesting,
  1169. although the need to do such a thing may indicate
  1170. that the inner constructs should be broken out into
  1171. a separate function, with a success/failure return code.
  1172. .Ex
  1173.     for (...) {
  1174.         while (...) {
  1175.             ...
  1176.             if (disaster)
  1177.                 goto error;
  1178.         
  1179.         }
  1180.     }
  1181.     \&...
  1182. error:
  1183.     clean up the mess
  1184. .Ee
  1185. When a
  1186. .Ec goto
  1187. is necessary the accompanying label should be alone
  1188. on a line and tabbed one stop to the left of the
  1189. code that follows.
  1190. The goto should be commented (possibly in the block header)
  1191. as to its utility and purpose.
  1192. .Ec Continue
  1193. should be used sparingly and near the top of the loop.
  1194. .Ec Break
  1195. is less troublesome.
  1196. .PP
  1197. Parameters to non-prototyped functions sometimes need to be promoted
  1198. explicitly.
  1199. If, for example, a function expects a 32-bit
  1200. .Ec long
  1201. and gets handed a 16-bit
  1202. .Ec int
  1203. instead,
  1204. the stack can get misaligned.
  1205. Problems occur with pointer, integral, and floating-point values.
  1206. .NH
  1207. Compound Statements
  1208. .PP
  1209. A compound statement is a list of statements enclosed by braces.
  1210. There are many common ways of formatting the braces.
  1211. Be consistent with your local standard, if you have one,
  1212. or pick one and use it consistently.
  1213. When editing someone else's code, \fIalways\fP use the style
  1214. used in that code.
  1215. .Ex
  1216. control {
  1217. \ \ \ \ \ \ \ \ statement;
  1218. \ \ \ \ \ \ \ \ statement;
  1219. }
  1220. .Ee
  1221. .Ee
  1222. .LP
  1223. The style above is called ``K\^&\^R style'', and is
  1224. preferred if you haven't already got a favorite.
  1225. With K&R style, the
  1226. .Ep else
  1227. part of an
  1228. \fIif-else\fP statement
  1229. and the
  1230. .Ep while
  1231. part of a \fIdo-while\fP statement
  1232. should appear on the same line as the close brace.
  1233. With most other styles, the braces are always alone on a line.
  1234. .PP
  1235. When a block of code has several labels
  1236. (unless there are a lot of them),
  1237. the labels are placed on separate lines.
  1238. The fall-through feature of the C \fIswitch\fP statement,
  1239. (that is, when there is no
  1240. .Ep break
  1241. between a code segment and the next
  1242. .Ep case
  1243. statement)
  1244. must be commented for future maintenance.
  1245. A lint-style comment/directive is best.
  1246. .Ex
  1247. switch (expr) {
  1248. case ABC:
  1249. case DEF:
  1250.     statement;
  1251.     break;
  1252. case UVW:
  1253.     statement;
  1254.     /*FALLTHROUGH*/
  1255. case XYZ:
  1256.     statement;
  1257.     break;
  1258. }
  1259. .Ee
  1260. .\"
  1261. .\" You won't believe how long I struggled with the format of the
  1262. .\" `switch' statement.  It took a lot of people beating on me to
  1263. .\" convince me that it should look like the if...else arrangement
  1264. .\" that I said is supposed to ``look like a generalized switch''.
  1265. .\" Ok, so I'm a little slow some years...
  1266. .\"
  1267. .PP
  1268. Here, the last
  1269. .Ep break
  1270. is unnecessary, but is required
  1271. because it prevents a fall-through error if another
  1272. .Ep case
  1273. is added later after the last one.
  1274. The
  1275. .Ep default
  1276. case, if used, should be last and does not require a
  1277. .Ep break 
  1278. if it is last.
  1279. .PP
  1280. Whenever an
  1281. .Ec if-else
  1282. statement has a compound statement for either the
  1283. .Ec if
  1284. or
  1285. .Ec else
  1286. section, the statements of both the
  1287. .Ec if
  1288. and
  1289. .Ec else
  1290. sections should both be enclosed in braces
  1291. (called \fIfully bracketed syntax\fP).
  1292. .PP
  1293. .Ex
  1294. if (expr) {
  1295.     statement;
  1296. } else {
  1297.     statement;
  1298.     statement;
  1299. }
  1300. .Ee
  1301. Braces are also essential in \fIif-if-else\fP sequences
  1302. with no second \fIelse\fP such as the following,
  1303. which will be parsed incorrectly if the brace after
  1304. .Ep (ex1)
  1305. and its mate are omitted:
  1306. .Ex
  1307. if (ex1) {
  1308.     if (ex2) {
  1309.         funca();
  1310.     }
  1311. } else {
  1312.     funcb();
  1313. }
  1314. .Ee
  1315. .PP
  1316. An \fIif-else\fP with \fIelse if\fP should
  1317. be written with the \fIelse\fP conditions left-justified.
  1318. .Ex
  1319. if (STREQ (reply, "yes")) {
  1320.     statements for yes
  1321.     ...
  1322. } else if (STREQ (reply, "no")) {
  1323.     ...
  1324. } else if (STREQ (reply, "maybe")) {
  1325.     ...
  1326. } else {
  1327.     statements for default
  1328.     ...
  1329. }
  1330. .Ee
  1331. The format then looks
  1332. like a generalized \fIswitch\fP statement and the
  1333. tabbing reflects the switch between exactly one of several
  1334. alternatives rather than a nesting of statements.
  1335. .PP
  1336. .Ec Do-while
  1337. loops should always have braces around the body. 
  1338. .PP
  1339. The following code is very dangerous:
  1340. .Ex
  1341. #ifdef CIRCUIT
  1342. #    define CLOSE_CIRCUIT(circno)    { close_circ(circno); }
  1343. #else
  1344. #    define CLOSE_CIRCUIT(circno)
  1345. #endif
  1346.  
  1347. \&    ...
  1348.     if (expr)
  1349.         statement;
  1350.     else
  1351.         CLOSE_CIRCUIT(x)
  1352.     ++i;
  1353. .Ee
  1354. Note that on systems where CIRCUIT is not defined
  1355. the statement
  1356. .Ep ++i; '' ``
  1357. will only
  1358. get executed when
  1359. .Ep expr
  1360. is false!
  1361. This example points out both the value
  1362. of naming macros with CAPS and
  1363. of making code fully-bracketed.
  1364. .PP
  1365. Sometimes an
  1366. .Ec if
  1367. causes an unconditional control transfer
  1368. via
  1369. .Ep break ,
  1370. .Ep continue ,
  1371. .Ep goto ,
  1372. or
  1373. .Ep return .
  1374. The
  1375. .Ec else
  1376. should be implicit and the code should not be indented.
  1377. .Ex
  1378. if (level > limit)
  1379.     return (OVERFLOW)
  1380. normal();
  1381. return (level);
  1382. .Ee
  1383. The ``flattened'' indentation tells the reader that the boolean test
  1384. is invariant over the rest of the enclosing block.
  1385. .NH
  1386. Operators
  1387. .PP
  1388. Unary operators should not be separated from their single operand.
  1389. Generally, all binary operators
  1390. except
  1391. .Ep "\&." ' `
  1392. and
  1393. .Ep "\->" ' `
  1394. should be separated from their operands by blanks.
  1395. Some judgement is called for in the case of complex expressions,
  1396. which may be clearer if the ``inner'' operators are not surrounded
  1397. by spaces and the ``outer'' ones are.
  1398. .PP
  1399. If you think an expression will be hard to read,
  1400. consider breaking it across lines.
  1401. Splitting at the lowest-precedence operator near the break is best.
  1402. Since C has some unexpected precedence rules,
  1403. expressions involving mixed operators should be parenthesized.
  1404. Too many parentheses, however,
  1405. can make a line \fIharder\fP to read
  1406. because humans aren't good at parenthesis-matching.
  1407. .PP
  1408. There is a time and place for the binary comma operator,
  1409. but generally it should be avoided.
  1410. The comma operator is most useful
  1411. to provide multiple initializations or operations,
  1412. as in \fIfor\fP statements.
  1413. Complex expressions,
  1414. for instance those with nested ternary
  1415. .Ec ?\^:
  1416. operators,
  1417. can be confusing and should be avoided if possible.
  1418. There are some macros like
  1419. .Ep getchar
  1420. where both the ternary
  1421. operator and comma operators are useful.
  1422. The logical expression operand before the
  1423. .Ec ?\^:
  1424. should be parenthesized and both return values must be the same type.
  1425. .NH
  1426. Naming Conventions
  1427. .PP
  1428. Individual projects will no doubt have their own naming conventions.
  1429. There are some general rules however.
  1430. .IP \0\0\(bu
  1431. Names with leading and trailing underscores are reserved for system
  1432. purposes and should not be used for any user-created names.
  1433. Most systems use them for names
  1434. that the user should not have to know.
  1435. If you must have your own private identifiers,
  1436. begin them with a letter or two identifying the
  1437. package to which they belong.
  1438. .IP \0\0\(bu
  1439. #define constants should be in all CAPS.
  1440. .IP \0\0\(bu
  1441. Enum constants are Capitalized or in all CAPS
  1442. .IP \0\0\(bu
  1443. Function, typedef, and variable names, as well as struct, union, and
  1444. enum tag names should be in lower case.
  1445. .IP \0\0\(bu
  1446. Many macro ``functions'' are in all CAPS.
  1447. Some macros (such as
  1448. .Ep getchar
  1449. and
  1450. .Ep putchar )
  1451. are in lower case
  1452. since they may also exist as functions.
  1453. Lower-case macro names are only acceptable if the macros behave
  1454. like a function call,
  1455. that is, they evaluate their parameters \fIexactly\fP once and
  1456. do not assign values to named parameters.
  1457. Sometimes it is impossible to write a macro that behaves like a
  1458. function even though the arguments are evaluated exactly once.
  1459. .IP \0\0\(bu
  1460. Avoid names that differ only in case, like \fIfoo\fP and \fIFoo\fP.
  1461. Similarly, avoid \fIfoobar\fP and \fIfoo_bar\fP.
  1462. The potential for confusion is considerable.
  1463. .IP \0\0\(bu
  1464. Similarly, avoid names that look like each other.
  1465. On many terminals and printers, `l', `1' and `I' look quite similar.
  1466. A variable named `l' is particularly bad because it looks so much like
  1467. the constant `1'.
  1468. .PP
  1469. In general, global names (including
  1470. .Ec enum s)
  1471. should have a
  1472. common prefix identifying the module that they belong with.
  1473. Globals may alternatively be grouped in a global structure.
  1474. Typedeffed names often have
  1475. .Ep _t '' ``
  1476. appended to their name.
  1477. .PP
  1478. Avoid names that might conflict with various standard
  1479. library names.
  1480. Some systems will include more library code than you want.
  1481. Also, your program may be extended someday.
  1482. .NH
  1483. Constants
  1484. .PP
  1485. Numerical constants should not be coded directly.
  1486. The
  1487. .Ec #define
  1488. feature of the C preprocessor should be used to
  1489. give constants meaningful names.
  1490. Symbolic constants make the code easier to read.
  1491. Defining the value in one place
  1492. also makes it easier to administer large programs since the
  1493. constant value can be changed uniformly by changing only the
  1494. define.
  1495. The enumeration data type is a better way to declare variables
  1496. that take on only a discrete set of values, since
  1497. additional type checking is often available.
  1498. At the very least, any directly-coded numerical constant must have a
  1499. comment explaining the derivation of the value.
  1500. .PP
  1501. Constants should be defined consistently with their use;
  1502. e.g. use
  1503. .Ep 540.0
  1504. for a float instead of
  1505. .Ep 540
  1506. with an implicit float cast.
  1507. There are some cases where the constants 0 and 1 may appear as
  1508. themselves instead of as defines.
  1509. For example if a
  1510. .Ec for
  1511. loop indexes through an array, then
  1512. .Ex
  1513. for (i = 0; i < ARYBOUND; i++)
  1514. .Ee
  1515. is reasonable while the code
  1516. .Ex
  1517. door_t *front_door = opens(door[i], 7);
  1518. if (front_door =\^= 0)
  1519.     error("can't open %s\\\\n", door[i]);
  1520. .Ee
  1521. is not.
  1522. In the last example
  1523. .Ep front_door
  1524. is a pointer.
  1525. When a value is a pointer it should be compared to
  1526. .Ep NULL
  1527. instead of 0.
  1528. .Ec NULL
  1529. is available
  1530. either as part of the standard I/O library's header file \fIstdio.h\fP
  1531. or in \fIstdlib.h\fP for newer systems.
  1532. Even simple values like 1 or 0 are often better expressed using
  1533. defines like
  1534. .Ec TRUE
  1535. and
  1536. .Ec FALSE
  1537. (sometimes
  1538. .Ec YES
  1539. and
  1540. .Ec NO
  1541. read better).
  1542. .PP
  1543. Simple character constants should be defined as character literals
  1544. rather than numbers.
  1545. Non-text characters are discouraged as non-portable.
  1546. If non-text characters are necessary,
  1547. particularly if they are used in strings,
  1548. they should be written using a escape character of three octal digits
  1549. rather than one
  1550. (e.g.,
  1551. .Ep \&'\&\e007' ).
  1552. Even so, such usage should be considered machine-dependent and treated
  1553. as such.
  1554. .NH
  1555. Macros
  1556. .PP
  1557. Complex expressions can be used as macro parameters,
  1558. and operator-precedence problems can arise unless all occurrences of
  1559. parameters have parentheses around them.
  1560. There is little that can be done about the problems caused by side
  1561. effects in parameters
  1562. except to avoid side effects in expressions (a good idea anyway)
  1563. and, when possible,
  1564. to write macros that evaluate their parameters exactly once.
  1565. There are times when it is impossible to write macros that act exactly
  1566. like functions.
  1567. .\" .PP
  1568. .\" Here are some classic macros.
  1569. .\" .DS
  1570. .\" #define INV(val)    1/val
  1571. .\" \&...
  1572. .\"     y = INV(*x);        /* turns into ``start comment''! */
  1573. .\" .DE
  1574. .\" (The above does \fInot\fP start a comment with ANSI preprocesors.)
  1575. .\" .DS
  1576. .\" #define MAX(a,b)    (((a)>(b)) ? (a) : (b) )
  1577. .\" \&...
  1578. .\"     k = MAX(i++,j++);
  1579. .\" .DE
  1580. .PP
  1581. Some macros also exist as functions (e.g.,
  1582. .Ep getc
  1583. and
  1584. .Ep fgetc ).
  1585. The macro should be used in implementing the function
  1586. so that changes to the macro
  1587. will be automatically reflected in the function.
  1588. Care is needed when interchanging macros and functions since function
  1589. parameters are passed by value, while macro parameters are passed by
  1590. name substitution.
  1591. .\" Carefree use of macros requires care when they are defined.
  1592. Carefree use of macros requires that they be declared carefully.
  1593. .PP
  1594. Macros should avoid using globals, since the global name may be
  1595. hidden by a local declaration.
  1596. Macros that change named parameters (rather than the storage they
  1597. point at) or may be used as the left-hand side of an assignment
  1598. should mention this in their comments.
  1599. Macros that take no parameters but reference variables,
  1600. are long,
  1601. or are aliases for function calls
  1602. should be given an empty parameter list, e.g.,
  1603. .Ex
  1604. #define    OFF_A(\^\^)    (a_global+OFFSET)
  1605. #define    BORK(\^\^)    (zork(\^))
  1606. #define    SP3(\^\^)    if (b) { int x; av = f (&x); bv += x; }
  1607. .Ee
  1608. .PP
  1609. Macros save function call/return overhead,
  1610. but when a macro gets long, the effect of the call/return
  1611. becomes negligible, so a function should be used instead.
  1612. .PP
  1613. In some cases it is appropriate to make the compiler
  1614. insure that a macro is terminated with a semicolon.
  1615. .Ex
  1616. if (x==3)
  1617.     SP3(\^\^);
  1618. else
  1619.     BORK(\^\^);
  1620. .Ee
  1621. If the semicolon is omitted after the call to
  1622. .Ep SP3 ,
  1623. then the
  1624. .Ep else
  1625. will (silently!) become associated with the
  1626. .Ep if
  1627. in the
  1628. .Ep SP3
  1629. macro.
  1630. With the semicolon, the
  1631. .Ep else
  1632. doesn't match \fBany\fP
  1633. .Ep if !
  1634. The macro
  1635. .Ep SP3
  1636. can be written safely as
  1637. .Ex
  1638. #define SP3(\^\^) \\\\
  1639.     do { if (b) { int x; av = f (&x); bv += x; }} while (0)
  1640. .Ee
  1641. Writing out the enclosing
  1642. .Ec do-while
  1643. by hand is awkward and some compilers and tools
  1644. may complain that there is a constant in the
  1645. .Ep while '' ``
  1646. conditional.
  1647. A macro for declaring statements may make programming easier.
  1648. .Ex
  1649. #ifdef lint
  1650.     static int ZERO;
  1651. #else
  1652. #    define ZERO 0
  1653. #endif
  1654. #define STMT( stuff )        do { stuff } while (ZERO)
  1655. .Ee
  1656. Declare
  1657. .Ep SP3
  1658. with
  1659. .Ex
  1660. #define SP3(\^\^) \\\\
  1661.     STMT( if (b) { int x; av = f (&x); bv += x; } )
  1662. .Ee
  1663. Using
  1664. .Ep STMT
  1665. will help prevent small typos from silently changing programs.
  1666. .PP
  1667. Except for type casts,
  1668. .Ep sizeof ,
  1669. and hacks such as the above,
  1670. macros should contain keywords only if the entire
  1671. macro is surrounded by braces.
  1672. .NH
  1673. Conditional Compilation.
  1674. .PP
  1675. Conditional compilation is useful for things like
  1676. machine-dependencies,
  1677. debugging,
  1678. and for setting certain options at compile-time.
  1679. Beware of conditional compilation.
  1680. Various controls can easily combine in unforeseen ways.
  1681. If you #ifdef machine dependencies,
  1682. make sure that when no machine is specified,
  1683. the result is an error, not a default machine.
  1684. (Use
  1685. .Ep #error '' ``
  1686. and indent it so it works with older compilers.)
  1687. If you #ifdef optimizations,
  1688. the default should be the unoptimized code
  1689. rather than an uncompilable program.
  1690. Be sure to test the unoptimized code.
  1691. .PP
  1692. Note that the text inside of an #ifdeffed section may be scanned
  1693. (processed) by the compiler, even if the #ifdef is false.
  1694. Thus, even if the #ifdeffed part of the file never gets compiled
  1695. (e.g.,
  1696. .Ep "#ifdef COMMENT" ),
  1697. it cannot be arbitrary text.
  1698. .PP
  1699. Put #ifdefs in header files instead of source files when possible.
  1700. Use the #ifdefs to define macros
  1701. that can be used uniformly in the code.
  1702. For instance, a header file for checking memory allocation
  1703. might look like (omitting definitions for
  1704. .Ep REALLOC
  1705. and
  1706. .Ep FREE ):
  1707. .Ex
  1708. #ifdef DEBUG
  1709.     extern void *mm_malloc();
  1710. #    define MALLOC(size) (mm_malloc(size))
  1711. #else
  1712.     extern void *malloc();
  1713. #    define MALLOC(size) (malloc(size))
  1714. #endif
  1715. .Ee
  1716. .PP
  1717. Conditional compilation should generally be
  1718. on a feature-by-feature basis.
  1719. Machine or operating system dependencies
  1720. should be avoided in most cases.
  1721. .Ex
  1722. #ifdef BSD4
  1723.     long t = time ((long *)NULL);
  1724. #endif
  1725. .Ee
  1726. The preceding code is poor for two reasons:
  1727. there may be 4BSD systems for which there is a better choice,
  1728. and there may be non-4BSD systems for which the above \fIis\fP the
  1729. best code.
  1730. Instead, use \fIdefine\fP symbols
  1731. such as
  1732. .Ep TIME_LONG
  1733. and
  1734. .Ep TIME_STRUCT
  1735. and define the appropriate one
  1736. in a configuration file such as \fIconfig.h\fP.
  1737. .NH
  1738. Debugging
  1739. .QP
  1740. .ce
  1741. ``\fIC Code.  C code run.  Run, code, run...  PLEASE!!!\fP'' \(em Barbara Tongue
  1742. .\"
  1743. .\" Recently: "C Code.  C Code Run.  Run, Code, RUN!  PLEASE!!!"
  1744. .\" But I think the original is accurate.
  1745. .\"
  1746. .PP
  1747. If you use
  1748. .Ec enum s,
  1749. the first enum constant should have a non-zero value,
  1750. or the first constant should indicate an error.
  1751. .Ex
  1752. enum { STATE_ERR, STATE_START, STATE_NORMAL, STATE_END } state_t;
  1753. enum { VAL_NEW=1, VAL_NORMAL, VAL_DYING, VAL_DEAD } value_t;
  1754. .Ee
  1755. Uninitialized values will then often ``catch themselves''.
  1756. .PP
  1757. Check for error return values, even from functions that ``can't''
  1758. fail.
  1759. Consider that
  1760. .Ep close(\^)
  1761. and
  1762. .Ep fclose(\^)
  1763. can and do fail, even when all prior file operations have succeeded.
  1764. Write your own functions so that they test for errors
  1765. and return error values or abort the program in a well-defined way.
  1766. Include a lot of debugging and error-checking code
  1767. and leave most of it in the finished product.
  1768. Check even for ``impossible'' errors. [8]
  1769. .PP
  1770. Use the
  1771. .Ec assert
  1772. facility to insist that
  1773. each function is being passed well-defined values,
  1774. and that intermediate results are well-formed.
  1775. .PP
  1776. Build in the debug code using as few #ifdefs as possible.
  1777. For instance, if
  1778. .Ep mm_malloc '' ``
  1779. is a debugging memory allocator, then
  1780. .Ep MALLOC
  1781. will select the appropriate allocator,
  1782. avoids littering the code with #ifdefs,
  1783. and makes clear the difference between allocation calls being debugged
  1784. and extra memory that is allocated only during debugging.
  1785. .Ex
  1786. #ifdef DEBUG
  1787. #    define MALLOC(size)  (mm_malloc(size))
  1788. #else
  1789. #    define MALLOC(size)  (malloc(size))
  1790. #endif
  1791. .Ee
  1792. .PP
  1793. Check bounds even on things that ``can't'' overflow.
  1794. A function that writes on to variable-sized storage
  1795. should take an argument
  1796. .Ep maxsize
  1797. that is the size of the destination.
  1798. If there are times when the size of the destination is unknown,
  1799. some `magic' value of
  1800. .Ep maxsize
  1801. should mean ``no bounds checks''.
  1802. When bound checks fail,
  1803. make sure that the function does something useful
  1804. such as abort or return an error status.
  1805. .Ex
  1806. /*
  1807.  * INPUT: A null-terminated source string `src' to copy from and
  1808.  * a `dest' string to copy to.  `maxsize' is the size of `dest'
  1809.  * or UINT_MAX if the size is not known.  `src' and `dest' must
  1810.  * both be shorter than UINT_MAX, and `src' must be no longer than
  1811.  * `dest'.
  1812.  * OUTPUT: The address of `dest' or NULL if the copy fails.
  1813.  * `dest' is modified even when the copy fails.
  1814.  */
  1815.     char *
  1816. copy (dest, maxsize, src)
  1817.     char *dest, *src;
  1818.     unsigned maxsize;
  1819. .\"
  1820. .\" That should be `size_t', rather than `unsigned'?
  1821. .\"
  1822. {
  1823.     char *dp = dest;
  1824.  
  1825.     while (maxsize\-\^\- > 0)
  1826.         if ((*dp++ = *src++) =\^= '\\\\0')
  1827.             return (dest);
  1828.  
  1829.     return (NULL);
  1830. }
  1831. .Ee
  1832. .PP
  1833. In all, remember that
  1834. a program that produces wrong answers twice as fast is infinitely
  1835. slower.
  1836. The same is true of programs that crash occasionally
  1837. or clobber valid data.
  1838. .NH
  1839. Portability
  1840. .QP
  1841. .ad r
  1842. ``\fIC combines the power of assembler with
  1843. the portability of assembler.\fP''
  1844. .br
  1845. \(em Anonymous, alluding to Bill Thacker.
  1846. .br
  1847. .ad b
  1848. .LP
  1849. .\"
  1850. .\" .QP
  1851. .\" .ad r
  1852. .\" ``\fI"C" combines the power of assembly language with
  1853. .\" the flexibility of assembly language.\fP''
  1854. .\" .br
  1855. .\" \(em Bill Thacker
  1856. .\" .ad b
  1857. .\"
  1858. .PP
  1859. The advantages of portable code are well known.
  1860. This section gives some guidelines for writing portable code.
  1861. Here, ``portable'' means that a source file
  1862. can be compiled and executed on different machines
  1863. with the only change being the inclusion of possibly
  1864. different header files and the use of different compiler flags.
  1865. The header files will contain #defines and typedefs that may vary from
  1866. machine to machine.
  1867. In general, a new ``machine'' is different hardware,
  1868. a different operating system, a different compiler,
  1869. or any combination of these.
  1870. Reference [1] contains useful information on both style and portability.
  1871. .\" Does it really?
  1872. The following is a list of pitfalls to be avoided and recommendations
  1873. to be considered when designing portable code:
  1874. .IP \0\0\(bu
  1875. Write portable code first,
  1876. worry about detail optimizations only on machines where they
  1877. prove necessary.
  1878. Optimized code is often obscure.
  1879. Optimizations for one machine may produce worse code on another.
  1880. Document performance hacks and localize them as much as possible.
  1881. Documentation should explain \fIhow\fP it works and \fIwhy\fP
  1882. it was needed (e.g., ``loop executes 6 zillion times'').
  1883. .IP \0\0\(bu
  1884. Recognize that some things are inherently non-portable.
  1885. Examples are code to deal with particular hardware registers such as
  1886. the program status word,
  1887. and code that is designed to support a particular piece of hardware,
  1888. such as an assembler or I/O driver.
  1889. Even in these cases there are many routines and data organizations
  1890. that can be made machine independent.
  1891. .IP \0\0\(bu
  1892. Organize source files so that the machine-independent
  1893. code and the machine-dependent code are in separate files.
  1894. Then if the program is to be moved to a new machine,
  1895. it is a much easier task to determine what needs to be changed.
  1896. Comment the machine dependence in the headers of the appropriate
  1897. files.
  1898. .IP \0\0\(bu
  1899. Any behavior that is described as ``implementation defined''
  1900. should be treated as a machine (compiler) dependency.
  1901. Assume that the compiler or hardware does it some completely screwy
  1902. way.
  1903. .IP \0\0\(bu
  1904. Pay attention to word sizes.
  1905. Objects may be non-intuitive sizes,
  1906. Pointers are not always the same size as \fIint\fPs,
  1907. the same size as each other,
  1908. or freely interconvertible.
  1909. The following table shows bit sizes for basic types in C for various
  1910. machines and compilers.
  1911. .br
  1912. .ne 2i
  1913. .TS
  1914. center;
  1915. l c c c c c c c
  1916. l c c c c c c c
  1917. l r r r r r r r.
  1918. type    pdp11    VAX/11    68000    Cray-2    Unisys    Harris    80386
  1919.     series        family        1100    H800    
  1920. _
  1921. char    8    8    8    8    9    8    8
  1922. short    16    16    8/16    64(32)    18    24    8/16
  1923. int    16    32    16/32    64(32)    36    24    16/32
  1924. long    32    32    32    64    36    48    32
  1925. char*    16    32    32    64    72    24    16/32/48
  1926. int*    16    32    32    64(24)    72    24    16/32/48
  1927. int(*)(\^\^)    16    32    32    64    576    24    16/32/48
  1928. .TE
  1929. .\" 
  1930. .\" blarson%skat.usc.edu@oberon.usc.edu (Bob Larson) sez for a pr1me
  1931. .\" int=16 is a compile-time option.  pointer size depends on which
  1932. .\" instruction set you generate code for, only 32 bits are significant
  1933. .\" on non-char* pointers (extra 16 bits allocated but not used.)
  1934. .\" 
  1935. .\" beaver.cs.washington.edu!cornell!calvin!johns (John Sahr) sez
  1936. .\" the Harris H800/H100 series has 3-byte words.  Float and double
  1937. .\" are the same bit-size but are different precision; two bytes are
  1938. .\" thrown away for floats.  Int* and char* are same size but 2 bits
  1939. .\" are reserved for the byte pointer within a word.  H1000/H12000
  1940. .\" have software triple and quad precision for FORTRAN, 9 & 12 bytes.
  1941. .\"
  1942. .\" Theodore Stevens Norvell <norvell@csri.toronto.edu> on the Control
  1943. .\" Data Cyber-180 (aka Cyber 900).  Pointers hold only 48 bits of
  1944. .\" useful data (44 for virtual byte address, 4 for security) but are
  1945. .\" padded to make them more interchangeable with ints.
  1946. .\" 
  1947. .\" DEEBE@SCIENCE.UTAH.EDU (Nelson H.F. Beebe) on 36-bit DEC-20:
  1948. .\" 4 compilers, including PCC-20 (Johnson's PCC ported to TOPS-20 by
  1949. .\" Lereau@cs.utah.edu), KCC-20 (Kok Chen at Stanford, Ken Harrenstien
  1950. .\" and Ian Macky at SRI), New Mexico Tech C, Sargasso C compiler
  1951. .\" (from BBN, he thinks).  Most still using DEC-20's use KCC.
  1952. .\" [*] Note that KCC-20 has 4 pointer formats based on local/global
  1953. .\" and char*/non-char* usage.  The following fails:
  1954. .\"     int *p = malloc( sizeof(int) );
  1955. .\"    free( p );
  1956. .\" It works correctly with casts to int* from malloc and to char* for
  1957. .\" free.
  1958. .\" 
  1959. .\" type    pr1me    H800    Cyber    PCC-20    KCC-20
  1960. .\"                900
  1961. .\"
  1962. .\" char    8    8    8    36    9
  1963. .\" short    16    24    32    36    18
  1964. .\" int        16/32    24    64    36    36
  1965. .\" long    32    48    64    36    36
  1966. .\" char*    32(48)    24    64    36    36[*]
  1967. .\" int*    32(48)    ?    64    36    36[*]
  1968. .\" int(*)()    32(48)    24    64    36    36[*]
  1969. .\" float    ?    48    64    36    36
  1970. .\" double    ?    48    64    36    72
  1971. .\" long double    ?    ?    128    <none>    <none>
  1972. .\" 
  1973. Some machines have more than one possible size for a given type.
  1974. The size you get can depend both on the compiler
  1975. and on various compile-time flags.
  1976. The following table shows ``safe'' type sizes on the majority of
  1977. systems.
  1978. Unsigned numbers are the same bit size as signed numbers.
  1979. .KS
  1980. .TS
  1981. center;
  1982. c c c
  1983. l r c.
  1984. Type    Minimum    No Smaller
  1985.     # Bits    Than
  1986. _
  1987. char    8
  1988. short    16    char
  1989. int    16    short
  1990. long    32    int
  1991. float    24
  1992. double    38    float
  1993. any *    14
  1994. char *    15    any *
  1995. void *    15    any *
  1996. .TE
  1997. .KE
  1998. .IP \0\0\(bu
  1999. The
  2000. .Ec void*
  2001. type
  2002. is guaranteed to have enough bits
  2003. of precision to hold a pointer to any data object.
  2004. The
  2005. .Ec void(*)(\^\^)
  2006. type is guaranteed to be able to hold a pointer to any function.
  2007. Use these types when you need a generic pointer.
  2008. (Use
  2009. .Ec char*
  2010. and
  2011. .Ec char(*)(\^\^) ,
  2012. respectively, in older compilers).
  2013. .\"
  2014. .\" Any return value should do; `int(*)()' makes more sense,
  2015. .\" but then it's hard to #define back and forth between dpANS
  2016. .\" (void means void) and older compilers (#define void ...).
  2017. .\" You still bite the farm if the compiler understands void but
  2018. .\" not void*.
  2019. .\"
  2020. Be sure to cast pointers back to the correct type before using them.
  2021. .IP \0\0\(bu
  2022. Even when, say, an
  2023. .Ec int*
  2024. and a
  2025. .Ec char*
  2026. are the same \fIsize\fP, they may have different \fIformats\fP.
  2027. For example, the following will fail on some machines that have
  2028. .Ep sizeof(int*)
  2029. equal to
  2030. .Ep sizeof(char*) .
  2031. The code fails because
  2032. .Ep free
  2033. expects a
  2034. .Ec char*
  2035. and gets passed an
  2036. .Ec int* .
  2037. .\" See the comment above about the KCC compiler for DEC-20s
  2038. .Ex
  2039. int *p = (int *) malloc (sizeof(int));
  2040. free (p);
  2041. .Ee
  2042. .\"
  2043. .\" Another example:
  2044. .\" Consider the \fBqsort\fP routine, which takes a pointer to an array
  2045. .\" of `things', the size of each element, and a comparison function.
  2046. .\" Sorting an array of \fBstruct foo\fP, you may be tempted to say
  2047. .\" .Ex
  2048. .\" int compare (struct foo *a, struct foo *b) { ... }
  2049. .\" qsort ((void*)argv, argc, sizeof(struct foo), compare);
  2050. .\" .Ee
  2051. .\" This will surely bomb on some machines, however.
  2052. .\" .Ep compare(\^)
  2053. .\" takes pointers to two
  2054. .\" .Ec struct Ps,
  2055. .\" while
  2056. .\" .Ep qsort(\^)
  2057. .\" will \fIcall\fP it with two
  2058. .\" .Ec void* s.
  2059. .\"
  2060. .IP \0\0\(bu
  2061. Note that
  2062. the \fIsize\fP of an object does not guarantee the \fIprecision\fP of
  2063. that object.
  2064. The Cray-2 may use 64 bits to store an
  2065. .Ec int ,
  2066. but a \fIlong\fP cast into an
  2067. .Ec int
  2068. and back to a
  2069. .Ec long
  2070. may be truncated to 32 bits.
  2071. .IP \0\0\(bu
  2072. The integer
  2073. .Ec constant
  2074. zero may be cast to any pointer type.
  2075. The resulting pointer is called a
  2076. \fInull pointer\fP
  2077. for that type, and is different from any other pointer of that type.
  2078. A null pointer always compares equal to the constant zero.
  2079. A null pointer might \fInot\fP compare equal with a variable
  2080. that has the value zero.
  2081. Null pointers are \fInot\fP always stored with all bits zero.
  2082. Null pointers for two different types are sometimes different.
  2083. A null pointer of one type cast in to a pointer of another
  2084. type will be cast in to the null pointer for that second type.
  2085. .\"
  2086. .\" The name of the null pointer is called "NULL".
  2087. .\" But that's just what the name is called.
  2088. .\" The name is really "0" (cast or otherwise coerced to a pointer value).
  2089. .\" But again, that's just the name.
  2090. .\" The actual null pointer can have any bitwise value the implementor chooses.
  2091. .\"            -- Wayne Throop (alluding to Lewis Carroll)
  2092. .\"
  2093. .\" In C, the name of the nil pointer is called "NULL".
  2094. .\" But that's only what the name is CALLED, you see.
  2095. .\" The NAME of the nil pointer is "0".
  2096. .\" The nil pointer itself can have any bit pattern it pleases. 
  2097. .\"            -- Wayne Throop (alluding to Lewis Carroll)
  2098. .\"
  2099. .IP \0\0\(bu
  2100. On \s-1ANSI\s+1 compilers, when two pointers of the same type access
  2101. the same storage, they will compare as equal.
  2102. When non-zero integer constants are cast to pointer types,
  2103. they may become identical to other pointers.
  2104. On non-\s-1ANSI\s+1 compilers, pointers that
  2105. access the same storage may compare as different.
  2106. The following two pointers, for instance,
  2107. may or may not compare equal,
  2108. and they may or may not access the same storage\*f.
  2109. .FS
  2110. .IP \*F
  2111. The code may also fail to compile, fault on pointer creation,
  2112. fault on pointer comparison, or fault on pointer dereferences.
  2113. .FE
  2114. .Ex
  2115. ((int *) 2 )
  2116. ((int *) 3 )
  2117. .Ee
  2118. .\"
  2119. .\" This is true, for instance, on the 8086, where the least-
  2120. .\" -significant bit is always ignored, except when accessing
  2121. .\" byte-sized values.  The pointer comparison (==) uses \fIall\fP
  2122. .\" bits, so the two pointers do \fInot\fP compare the same.
  2123. .\"
  2124. If you need `magic' pointers other than NULL,
  2125. either allocate some storage or treat the pointer as
  2126. a machine dependence.
  2127. .Ex
  2128. extern int x_int_dummy;        /* in x.c */
  2129. #define X_FAIL    (NULL)
  2130. #define X_BUSY    (&x_int_dummy)
  2131. .Ee
  2132. .Ex
  2133. #define X_FAIL    (NULL)
  2134. #define X_BUSY    MD_PTR1        /* MD_PTR1 from "machdep.h" */
  2135. .Ee
  2136. .IP \0\0\(bu
  2137. Floating-point numbers have both a \fIprecision\fP and a \fIrange\fP.
  2138. These are independent of the size of the object.
  2139. Thus, overflow (underflow) for a 32-bit floating-point number will
  2140. happen at different values on different machines.
  2141. Also,
  2142. 4.9
  2143. times
  2144. 5.1
  2145. will yield
  2146. two different numbers on two different machines.
  2147. Differences in rounding and truncation can give surprisingly
  2148. different answers.
  2149. .\"
  2150. .\" .QP
  2151. .\" ``\fI10.0 times 0.1 is hardly ever 1.0\fP'' -- Kernighan and Plauger [9]
  2152. .\"
  2153. .IP \0\0\(bu
  2154. On some machines,
  2155. a
  2156. .Ec double
  2157. may have \fIless\fP range or precision than a
  2158. .Ec float .
  2159. .IP \0\0\(bu
  2160. On some machines the first half of a
  2161. .Ec double
  2162. may be a
  2163. .Ec float
  2164. with similar value.
  2165. Do \fInot\fP depend on this.
  2166. .IP \0\0\(bu
  2167. Watch out for signed characters.
  2168. On some \s-1VAX\s+1es, for instance,
  2169. characters are sign extended when used in expressions,
  2170. which is not the case on many other machines.
  2171. Code that assumes signed/unsigned is unportable.
  2172. For example,
  2173. .Ep array[c]
  2174. won't work if
  2175. .Ep c
  2176. is supposed to be positive and is instead signed and negative.
  2177. If you must assume signed or unsigned characters, comment them as
  2178. .Ep SIGNED
  2179. or
  2180. .Ep UNSIGNED .
  2181. Unsigned behavior can be guaranteed with
  2182. .Ep "unsigned char" .
  2183. .IP \0\0\(bu
  2184. Avoid assuming \s-1ASCII\s+1.
  2185. .\"
  2186. .\" (Use
  2187. .\" .Ep "<ctype.h>"
  2188. .\" where possible, but beware that their behavior varies considerably
  2189. .\" between C implementations.
  2190. .\" For instance, if c is not an upper-case letter,
  2191. .\" tolower(c) may return c or garbage.)
  2192. .\"
  2193. If you must assume, document and localize.
  2194. Remember that characters may hold (much) more than 8 bits.
  2195. .IP \0\0\(bu
  2196. Code that takes advantage of the two's complement representation of
  2197. numbers on most machines should not be used.
  2198. Optimizations that replace arithmetic operations with equivalent
  2199. shifting operations are particularly suspect.
  2200. If absolutely necessary, machine-dependent code should be #ifdeffed
  2201. or operations should be performed by #ifdeffed macros.
  2202. You should weigh the time savings with the potential for obscure
  2203. and difficult bugs when your code is moved.
  2204. .IP \0\0\(bu
  2205. In general, if the word size or value range is important,
  2206. typedef ``sized'' types.
  2207. Large programs should have a central header file which supplies
  2208. typedefs for commonly-used width-sensitive types, to make
  2209. it easier to change them and to aid in finding width-sensitive code.
  2210. Unsigned types other than
  2211. .Ec "unsigned int"
  2212. are highly compiler-dependent.
  2213. If a simple loop counter is being used where either 16 or 32 bits will
  2214. do, then use
  2215. .Ec int ,
  2216. since it will get the most efficient (natural)
  2217. unit for the current machine.
  2218. .\"
  2219. .\" <side comment>
  2220. .\" Actually, there are many machines that use ``unnatural''
  2221. .\" int sizes to cope with ``the world is a \s-1VAX\s+1'' problems.
  2222. .\" The rule int == natural is still true, though.
  2223. .\" Modern compilers have a switch that lets you select either
  2224. .\" efficiency or bogus-\s-1VAX\s+1-code-compatibility.
  2225. .\" On the other hand, this is still a lie, because the libraries
  2226. .\" must work in any event.
  2227. .\" On the other (third?) hand, modern systems are being fixed.
  2228. .\"
  2229. .IP \0\0\(bu
  2230. Data \fIalignment\fP is also important.
  2231. For instance,
  2232. on various machines a 4-byte integer may start at any address,
  2233. start only at an even address, or start only at a multiple-of-four
  2234. address.
  2235. Thus, a particular structure may have its elements
  2236. at different offsets on different machines,
  2237. even when given elements are the same size on all machines.
  2238. Indeed, a structure of a 32-bit pointer and an 8-bit character may be
  2239. 3 sizes on 3 different machines.
  2240. As a corollary, pointers to objects may not be interchanged freely;
  2241. saving an integer through a pointer
  2242. to 4 bytes starting at an odd address
  2243. will sometimes work,
  2244. sometimes cause a core dump,
  2245. and sometimes fail silently (clobbering other data in the process).
  2246. .\"
  2247. .\" In particular, the \s-1VAX\s+1 will work, the 68000 (tho' not necessarily
  2248. .\" other family members) will dump, and the 8086 (tho' not
  2249. .\" necessarily other members) will ignore the lowest bit.
  2250. .\" The IBM RT will silently round the address down to the nearest
  2251. .\" multiple of four.
  2252. .\"
  2253. Pointer-to-character is a particular trouble spot on machines which
  2254. do not address to the byte.
  2255. Alignment considerations and loader peculiarities make it very rash
  2256. to assume that two consecutively-declared variables are together
  2257. in memory, or that a variable of one type is aligned appropriately
  2258. to be used as another type.
  2259. .IP \0\0\(bu
  2260. The bytes of a word are of increasing significance with increasing
  2261. address on machines such as the \s-1VAX\s+1 (little-endian)
  2262. and of decreasing significance with increasing address on other
  2263. machines such as the 68000 (big-endian).
  2264. The order of bytes in a word and of words in larger
  2265. objects (say, a double word) might not be the same.
  2266. .\"
  2267. .\" Consider, for example, the PDP-11, in which words are
  2268. .\" little-endian, but the most-significant word of a long is stored
  2269. .\" first.
  2270. .\"
  2271. Hence any code that depends on the left-right orientation of bits
  2272. in an object deserves special scrutiny.
  2273. Bit fields within structure members will only be portable so long as
  2274. two separate fields are never concatenated and treated as a unit. [1,3]
  2275. Actually, it is nonportable to concatenate \fIany\fP two variables.
  2276. .IP \0\0\(bu
  2277. There may be unused holes in structures.
  2278. Suspect unions used for type cheating.
  2279. Specifically, a value should not be stored as one type and retrieved as
  2280. another.
  2281. An explicit tag field for unions may be useful.
  2282. .\"
  2283. .\" .Ex
  2284. .\" enum union_tag_t { UT_ERROR, UT_INT, UT_FLOAT };
  2285. .\" struct good_t {
  2286. .\"     enum union_tag_t tag;
  2287. .\"     union {
  2288. .\"         int i;
  2289. .\"         float f;
  2290. .\"         } u;
  2291. .\" } good_t;
  2292. .\" .Ee
  2293. .\"
  2294. .IP \0\0\(bu
  2295. Different compilers use different conventions for returning
  2296. structures.
  2297. This causes a problem when libraries return structure values
  2298. to code compiled with a different compiler.
  2299. Structure pointers are not a problem.
  2300. .\"
  2301. .\" Potentially, \fIany\fP parameter passing mechanism will vary
  2302. .\" between compilers.
  2303. .\" In general, compilers return word-size units in a fixed register
  2304. .\" and (in general) structure pointers are word-sized, so structure
  2305. .\" pointers are not a problem.
  2306. .\"
  2307. .IP \0\0\(bu
  2308. Do not make assumptions about the parameter passing mechanism.
  2309. especially pointer sizes and parameter evaluation order, size, etc.
  2310. The following code, for instance, is \fIvery\fP nonportable.
  2311. .Ex
  2312.     c = foo (getchar(), getchar());
  2313.  
  2314.     char
  2315. foo (c1, c2, c3)
  2316.     char c1, c2, c3;
  2317. {
  2318.     char bar = *(&c1 + 1);
  2319.     return (bar);            /* often won't return c2 */
  2320. }
  2321. .\"
  2322. .\" It can be argued that if this *does* return c2, then
  2323. .\" sizeof(char) == sizeof(int).
  2324. .\"
  2325. .Ee
  2326. This example has lots of problems.
  2327. The stack may grow up or down
  2328. (indeed, there need not even be a stack!).
  2329. Parameters may be widened when they are passed,
  2330. so a
  2331. .Ec char
  2332. might be passed as an
  2333. .Ec int ,
  2334. for instance.
  2335. Arguments may be pushed left-to-right, right-to-left,
  2336. in arbitrary order, or passed in registers (not pushed at all).
  2337. The order of evaluation may differ from the order in which
  2338. they are pushed.
  2339. One compiler may use several (incompatible) calling conventions.
  2340. .\"
  2341. .\" <side comment>
  2342. .\" One machine (??), for instance pushes R-to-L for compatibility
  2343. .\" with Pascal, except for varargs, which are passed L-to-R to
  2344. .\" make varargs work.  This always works since Pascal functions
  2345. .\" are never called varargs.
  2346. .\"
  2347. .IP \0\0\(bu
  2348. On some machines, the null character pointer
  2349. .Ep "((char *)0)"
  2350. is treated the same way as a pointer to a null string.
  2351. Do \fInot\fP depend on this.
  2352. .IP \0\0\(bu
  2353. Do not modify string constants\*f.
  2354. .FS
  2355. .IP \*F
  2356. Some libraries attempt to modify and then restore read-only
  2357. string variables.
  2358. Programs sometimes won't port because of these broken libraries.
  2359. The libraries are getting better.
  2360. .FE
  2361. .\"
  2362. .\" .FS
  2363. .\" .IP \*F
  2364. .\" Note that an initialzed array is writable.
  2365. .\" .Ex
  2366. .\" char s[] = "/dev/tty??";
  2367. .\" .Ee
  2368. .\" .FE
  2369. .\"
  2370. One particularly notorious (bad) example is
  2371. .Ex
  2372. s = "/dev/tty??";
  2373. strcpy (&s[8], ttychars);
  2374. .Ee
  2375. .IP \0\0\(bu
  2376. The address space may have holes.
  2377. Simply \fBcomputing\fP the address
  2378. of an unallocated element in an array
  2379. (before or after the actual storage of the array)
  2380. may crash the program.
  2381. If the address is used in a comparison,
  2382. sometimes the program will run but clobber data, give wrong answers,
  2383. or loop forever.
  2384. In \s-1ANSI\s+1 C, a pointer into an array of objects may legally point to
  2385. the first element after the end of the array; this is usually safe
  2386. in older implementations.
  2387. This ``outside'' pointer may not be dereferenced.
  2388. .\"
  2389. .\" K&R1 does not guarantee this behavior.  See K&R1, pg 188-9.
  2390. .\" Most implementations allow it, and it was standardized as a
  2391. .\" result.  On some machines, however, it fails.  For example,
  2392. .\" on an i80x86, no memory segments are 64k.  Addresses look like
  2393. .\" <segment,base>.  If N bytes are allocated and byte N+1 falls off
  2394. .\" the end of the segment, the base will wrap around to zero but stay
  2395. .\" in the same segment.  For example, adding 1 to <4,65535> gives
  2396. .\" <4,0>, so if &s[N-1] == <4,65535>, then &s[N] == <4,0>, which
  2397. .\" compares as LESS than the address of the N-1'th element.
  2398. .\"
  2399. .IP \0\0\(bu
  2400. Only the
  2401. .Ep =\^=
  2402. and
  2403. .Ep !\^=
  2404. comparisons are defined for all pointers of a given type.
  2405. It is only portable to use
  2406. .Ep < ,
  2407. .Ep <= ,
  2408. .Ep > ,
  2409. or
  2410. .Ep >= 
  2411. to compare pointers when they both point in to
  2412. (or to the first element after) the same array.
  2413. It is likewise only portable to use arithmetic operators on pointers
  2414. that both point into the same array or the first element afterwards.
  2415. .IP \0\0\(bu
  2416. Word size also affects shifts and masks.
  2417. The following code will clear only the three rightmost bits of an
  2418. \fIint\fP on \fIsome\fP 68000s.
  2419. On other machines it will also clear the upper two bytes.
  2420. .Ex
  2421. x &= 0177770
  2422. .Ee
  2423. Use instead
  2424. .Ex
  2425. x &= ~07
  2426. .Ee
  2427. which works properly on all machines.
  2428. .\"
  2429. .\" Originally, I'd said something like ``the or operator (\ |\ ) does
  2430. .\" not have these problems'', but that's not true.
  2431. .\" Consider
  2432. .\" .Ep "foo |= 0177770"
  2433. .\" vs.
  2434. .\" .Ep "foo |= ~07" 
  2435. .\".
  2436. Bitfields do not have these problems.
  2437. .IP \0\0\(bu
  2438. Side effects within expressions can result in code
  2439. whose semantics are compiler-dependent, since C's order of evaluation
  2440. is explicitly undefined in most places.
  2441. Notorious examples include the following.
  2442. .Ex
  2443. a[i] = b[i++];
  2444. .Ee
  2445. In the above example, we know only that
  2446. the subscript into
  2447. .Ep b
  2448. has not been incremented.
  2449. The index into
  2450. .Ep a
  2451. could be the value of
  2452. .Ep i
  2453. either before or after the increment.
  2454. .Ex
  2455. struct bar_t { struct bar_t *next; } bar;
  2456. bar->next = bar = tmp;
  2457. .Ee
  2458. In the second example, the address of
  2459. .Ep bar->next '' ``
  2460. may be computed before the value is assigned to
  2461. .Ep bar ''. ``
  2462. .Ex
  2463. bar = bar->next = tmp;
  2464. .Ee
  2465. In the third example,
  2466. .Ep bar
  2467. can be assigned before
  2468. .Ep bar->next.
  2469. Although this \fIappears\fP to violate the rule that
  2470. ``assignment proceeds right-to-left'', it is a legal interpretation.
  2471. Consider the following example:
  2472. .Ex
  2473. long i;
  2474. short a[N];
  2475. i = old
  2476. i = a[i] = new;
  2477. .Ee
  2478. The value that
  2479. .Ep i '' ``
  2480. is assigned must be a value that is typed as if assignment
  2481. proceeded right-to-left.
  2482. However,
  2483. .Ep i '' ``
  2484. may be assigned the value
  2485. .Ep "(long)(short)new" '' ``
  2486. before
  2487. .Ep a[i] '' ``
  2488. is assigned to.
  2489. Compilers do differ.
  2490. .\"
  2491. .\" More: if you write
  2492. .\" 
  2493. .\"         short b;
  2494. .\"         long a,c;
  2495. .\"          ...
  2496. .\"         a = b = c;
  2497. .\" 
  2498. .\" assignment ``proceeds AS IF right-to-left''.  The following is a
  2499. .\" legal implementation:
  2500. .\" 
  2501. .\"         b = (short) c;
  2502. .\"         a = (long) b;
  2503. .\" 
  2504. .\" A compiler is also allowed to implement it as:
  2505. .\" 
  2506. .\"         a = (long) (short) c;
  2507. .\"         b = (short) c;
  2508. .\" 
  2509. .\" since the same values are being assigned in each case.  But the
  2510. .\" assignment is not "proceeding right to left" in the second
  2511. .\" example, because a is assigned before b is.  This matters if b is
  2512. .\" replaced with an expression.
  2513. .\"
  2514. .IP \0\0\(bu
  2515. Be suspicious of numeric values appearing in the code (``magic
  2516. numbers'').
  2517. .IP \0\0\(bu
  2518. Avoid preprocessor tricks.
  2519. Tricks such as using
  2520. .Ep /**/
  2521. for token pasting
  2522. and macros that rely on argument string expansion will break reliably.
  2523. .Ex
  2524. #define FOO(string)    (printf("string = %s",(string)))
  2525. \&...
  2526. FOO(filename);
  2527. .Ee
  2528. Will only sometimes be expanded to
  2529. .Ex
  2530. (printf("filename = %s",(filename)))
  2531. .Ee
  2532. Be aware, however, that tricky preprocessors may cause macros to break
  2533. \fIaccidentally\fP on some machines.
  2534. Consider the following two versions of a macro.
  2535. .Ex
  2536. #define LOOKUP(chr)    (a['c'+(chr)])    /* Works as intended. */
  2537. #define LOOKUP(c)    (a['c'+(c)])        /* Sometimes breaks. */
  2538. .Ee
  2539. The second version of
  2540. .Ep LOOKUP
  2541. can be expanded in two different ways
  2542. and will cause code to break mysteriously.
  2543. .IP \0\0\(bu
  2544. Become familiar with existing library functions and defines.
  2545. (But not \fItoo\fP familiar.
  2546. The internal details of library facilities, as opposed to their
  2547. external interfaces, are subject to change without warning.
  2548. They are also often quite unportable.)
  2549. You should not be writing your own string compare routine,
  2550. terminal control routines, or making
  2551. your own defines for system structures.
  2552. ``Rolling your own'' wastes your time and
  2553. makes your code less readable, because another reader has to
  2554. figure out whether you're doing something special in that reimplemented
  2555. stuff to justify its existence.
  2556. It also prevents your program
  2557. from taking advantage of any microcode assists or other
  2558. means of improving performance of system routines.
  2559. Furthermore, it's a fruitful source of bugs.
  2560. If possible, be aware of the \fIdifferences\fP between the common 
  2561. libraries (such as \s-1ANSI\s+1, \s-1POSIX\s+1, and so on).
  2562. .IP \0\0\(bu
  2563. Use \fIlint\fP when it is available.
  2564. It is a valuable tool for finding machine-dependent constructs as well
  2565. as other inconsistencies or program bugs that pass the compiler.
  2566. If your compiler has switches to turn on warnings, use them.
  2567. .IP \0\0\(bu
  2568. Suspect labels inside blocks with the
  2569. associated
  2570. .Ec switch
  2571. or
  2572. .Ec goto
  2573. outside the block.
  2574. .IP \0\0\(bu
  2575. Wherever the type is in doubt,
  2576. parameters should be cast to the appropriate type.
  2577. Always cast NULL when it appears in non-prototyped function calls.
  2578. Do not use function calls as a place to do type cheating.
  2579. C has confusing promotion rules, so be careful.
  2580. For example, if a function expects a 32-bit
  2581. .Ec long
  2582. and it is passed a 16-bit
  2583. .Ec int
  2584. the stack can get misaligned, the value can get promoted wrong, etc.
  2585. .IP \0\0\(bu
  2586. Use explicit casts when doing arithmetic
  2587. that mixes signed and unsigned values.
  2588. .IP \0\0\(bu
  2589. The inter-procedural goto,
  2590. .Ec longjmp ,
  2591. should be used with caution.
  2592. Many implementations ``forget'' to restore values in registers.
  2593. Declare critical values as
  2594. .Ec volatile
  2595. if you can or comment them as
  2596. .Ep VOLATILE .
  2597. .IP \0\0\(bu
  2598. Some linkers convert names to lower-case
  2599. and
  2600. some only recognize the first six letters as unique.
  2601. Programs may break quietly on these systems.
  2602. .IP \0\0\(bu
  2603. Beware of compiler extensions.
  2604. If used, document and
  2605. consider them as machine dependencies.
  2606. .IP \0\0\(bu
  2607. .\"
  2608. .\" <interesting, but most folks don't care?>
  2609. .\"
  2610. A program cannot generally execute code in the data
  2611. segment or write into the code segment.
  2612. Even when it can, there is no guarantee that it can do so reliably.
  2613. .\"
  2614. .\" Examples: one 80386 default protection won't let you write to the
  2615. .\" code segment or execute from the data segment.  An 88000 will let
  2616. .\" you execute from the data segment, but unless the I-cache is told
  2617. .\" \fIexplicitly\fP to watch for invalidations, there is no way to
  2618. .\" tell when the I-cache will be updated.  As a result, some of the
  2619. .\" bytes of the cached instructions may be updated while others are
  2620. .\" left unchanged!
  2621. .\"
  2622. .NH
  2623. ANSI C
  2624. .PP
  2625. Modern C compilers support some or all of the \s-1ANSI\s+1 proposed standard
  2626. C.
  2627. Whenever possible, write code to run under standard C, and use
  2628. features such as function prototypes, constant storage, and volatile
  2629. storage.
  2630. Standard C improves program performance by giving better information
  2631. to optimizers.
  2632. Standard C improves portability by insuring that all compilers
  2633. accept the same input language and by providing mechanisms
  2634. that try to hide machine dependencies or emit warnings about
  2635. code that may be machine-dependent.
  2636. .NH 2
  2637. Compatibility
  2638. .PP
  2639. Write code that is easy to port to older compilers.
  2640. For instance,
  2641. conditionally #define new (standard) keywords such as
  2642. .Ec const
  2643. and
  2644. .Ec volatile
  2645. in a global \fI.h\fP file.
  2646. Standard compilers pre-define the preprocessor symbol
  2647. .Ep _\^\^_STDC_\^\^_ \*f.
  2648. .FS
  2649. .IP \*F
  2650. Some compilers predefine
  2651. .Ep _\^\^_STDC_\^\^_
  2652. to be 0, in an attempt to indicate partial compliance with the \s-1ANSI\s+1 C
  2653. standard.
  2654. Unfortunately, it is not possible to determine \fIwhich\fP \s-1ANSI\s+1
  2655. facilities are provided.
  2656. Thus, such compilers are broken.
  2657. See the rule about
  2658. ``don't write around a broken compiler unless you are forced to.''
  2659. .\"
  2660. .\" Although the 1989 \s-1ANSI\s+1 standard (X3.159-1989)
  2661. .\" defines _\^\^_STDC_\^\^_ as 1, later
  2662. .\" versions may define it to be another number.
  2663. .\"
  2664. .\" There's nothing keeping a vendor from defining __STDC__ to 0, or 1, or
  2665. .\" "hi" or anything else.  It is guaranteed that a conforming
  2666. .\" compiler will have __STDC__ set, and in particular that an
  2667. .\" \s-1ANSI\s+1-89-compliant compiler will set it to 1.  However, ``A implies
  2668. .\" B'' does not mean ``B implies A''.  That is, a nonconformant
  2669. .\" compiler can do anything it damn well pleases: interpret `while'
  2670. .\" to mean `abort compilation', rearrange expressions arbitrarily, or
  2671. .\" even set __STDC__ to zero.  Such usage is  broken because the
  2672. .\" vendor KNOWS that users are expecting __STDC__ to mean \s-1ANSI\s+1
  2673. .\" compliant and the vendor also KNOWS that the compiler isn't
  2674. .\" \s-1ANSI\s+1-compliant.
  2675. .\"
  2676. .FE
  2677. The
  2678. .Ec void*
  2679. type is hard to get right simply,
  2680. since some older compilers understand
  2681. .Ep void
  2682. but not
  2683. .Ep void* .
  2684. It is easiest to create a new
  2685. (machine- and compiler-dependent)
  2686. .Ep VOIDP
  2687. type, usually
  2688. .Ec char*
  2689. on older compilers.
  2690. .Ex
  2691. #if _\^\^_STDC_\^\^_
  2692.     typedef void *voidp;
  2693. #    define COMPILER_SELECTED
  2694. #endif
  2695. #ifdef A_TARGET
  2696. #    define const
  2697. #    define volatile
  2698. #    define void int
  2699.     typedef char *voidp;
  2700. #    define COMPILER_SELECTED
  2701. #endif
  2702. #ifdef ...
  2703.     \&...
  2704. #endif
  2705. #ifdef COMPILER_SELECTED
  2706. #    undef COMPILER_SELECTED
  2707. #else
  2708.     { NO TARGET SELECTED! }
  2709. #endif
  2710. .\"
  2711. .\" Alternatively, we could do
  2712. .\"
  2713. .\" #ifdef __STDC__
  2714. .\"    ..
  2715. .\" #    define CONST const
  2716. .\" #    define VOLATILE volatile
  2717. .\" #else
  2718. .\"    ..
  2719. .\" #endif
  2720. .\"
  2721. .\" Is one of these better?  Probably not, it will be a strange
  2722. .\" anachronism when everybody has forgotten that const once didn't
  2723. .\" exist.
  2724. .\"
  2725. .Ee
  2726. .PP
  2727. Note that under ANSI C, the `#' for a preprocessor directive must be
  2728. the first non-whitespace character on a line.
  2729. Under older compilers it must be the first character on the line.
  2730. .PP
  2731. When a static function has a forward declaration, the forward
  2732. declaration must include the storage class.
  2733. For older compilers, the class must be
  2734. .Ec extern ''. ``
  2735. For \s-1ANSI\s+1 compilers, the class must be
  2736. .Ec static ''. ``
  2737. but global functions must still be declared as
  2738. .Ec extern ''. ``
  2739. Thus, forward declarations of static functions should use a #define
  2740. such as
  2741. .Ep FWD_STATIC
  2742. that is #ifdeffed as appropriate.
  2743. .PP
  2744. An
  2745. .Ep "#ifdef NAME" '' ``
  2746. should end with either
  2747. .Ep #endif '' ``
  2748. or
  2749. .Ep "#endif /* NAME */" '', ``
  2750. \fInot\fP with
  2751. .Ep "#endif NAME" ''. ``
  2752. The comment should not be used on short #ifdefs,
  2753. as it is clear from the code.
  2754. .PP
  2755. ANSI
  2756. .Ec trigraphs
  2757. may cause programs with strings containing
  2758. .Ep ?? '' ``
  2759. may break mysteriously.
  2760. .\"
  2761. .\" ``sed -e "s;??\\([-=(/)'<!>]\\);?\\\\?\\1;g"
  2762. .\" will fix them...    -- Karl Heuer
  2763. .\"
  2764. .NH 2
  2765. Formatting
  2766. .PP
  2767. The style for \s-1ANSI\s+1 C is the same as for regular C,
  2768. with two notable exceptions: storage qualifiers
  2769. and parameter lists.
  2770. .PP
  2771. Because
  2772. .Ep const
  2773. and
  2774. .Ep volatile
  2775. have strange binding rules,
  2776. .\"
  2777. .\" In particular, "char const *s, *t" means both `t' and `s' point
  2778. .\" to constant storage, while "char * const s, *t" means that s is
  2779. .\" a constant, but `t' isn't.
  2780. .\"
  2781. .\" I think.
  2782. .\"
  2783. .\" `*' binds differently than `const'.
  2784. .\"
  2785. each
  2786. .Ec const
  2787. or
  2788. .Ec volatile
  2789. object should have a separate declaration.
  2790. .Ex
  2791. int const *s;        /* YES */
  2792. int const *s, *t;    /* NO */
  2793. .Ee
  2794. .PP
  2795. Prototyped functions merge parameter declaration
  2796. and definition in to one list.
  2797. Parameters should be commented in the function comment.
  2798. .Ex
  2799. /*
  2800.  * `bp': boat trying to get in.
  2801.  * `stall': a list of stalls, never NULL.
  2802.  * returns stall number, 0 => no room.
  2803.  */
  2804.     int
  2805. enter_pier (boat_t const *bp, stall_t *stall)
  2806. {
  2807.     \&...
  2808. .Ee
  2809. .\" .NH 2
  2810. .\" Storage Qualifiers
  2811. .NH 2
  2812. Prototypes
  2813. .PP
  2814. Function prototypes should be used
  2815. to make code more robust and to make it run faster.
  2816. Unfortunately, the prototyped \fBdeclaration\fP
  2817. .Ex
  2818. extern void bork (char c);
  2819. .Ee
  2820. is incompatible with the \fBdefinition\fP
  2821. .Ex
  2822.     void
  2823. bork (c)
  2824.     char c;
  2825. \&...
  2826. .Ee
  2827. The prototype says that
  2828. .Ep c
  2829. is to be passed as the most natural type for the machine,
  2830. possibly a byte.
  2831. The non-prototyped (backwards-compatible) definition implies that
  2832. .Ep c
  2833. is always passed as an
  2834. .Ec int \*f.
  2835. .FS
  2836. .IP \*F
  2837. Such automatic type promotion is called
  2838. .Ec widening .
  2839. For older compilers, the widening rules require that
  2840. all
  2841. .Ec char
  2842. and
  2843. .Ec short
  2844. parameters are passed as
  2845. .Ec int s
  2846. and that
  2847. .Ec float
  2848. parameters are passed as
  2849. .Ec double s.
  2850. .FE
  2851. If a function has promotable parameters then 
  2852. the caller and callee must be compiled identically.
  2853. Either both must use function prototypes
  2854. or neither can use prototypes.
  2855. The problem can be avoided if parameters are promoted when the program
  2856. is designed.
  2857. For example,
  2858. .Ep bork
  2859. can be defined to take an
  2860. .Ec int
  2861. parameter.
  2862. .PP
  2863. The above declaration works if the definition is prototyped.
  2864. .Ex
  2865.     void
  2866. bork (char c)
  2867. {
  2868.     \&...
  2869. .Ee
  2870. Unfortunately,
  2871. the prototyped syntax will cause non-\s-1ANSI\s+1 compilers to reject the
  2872. program.
  2873. .\"
  2874. .\" There is no obvious way to define the function so that
  2875. .\" prototypes are used only when an \s-1ANSI\s+1 compiler is used.
  2876. .\" Prototyped and nonprototyped declarations can be #ifdeffed on
  2877. .\" .Ep _\^\^_STDC_\^\^_ ,
  2878. .\" but the extra #ifdeffing causes maintainance problems
  2879. .\" and makes the code hard to read.
  2880. .\"
  2881. .\" Oh yeah, try
  2882. .\"
  2883. .\"    int DEFUN (foo, (a, p), int a AND char *p)
  2884. .\"    int foo FUN2(int, a, char *, p)
  2885. .\"
  2886. .\" But beware: ``Don't change the syntax via macro substitution.''
  2887. .\"
  2888. .PP
  2889. It \fIis\fP easy to write external declarations that work with both
  2890. prototyping and with older compilers\*f.
  2891. .FS
  2892. .IP \*F
  2893. Note that using
  2894. .Ep PROTO
  2895. violates the rule ``don't change the syntax via macro substitution.''
  2896. It is regrettable that there isn't a better solution.
  2897. .FE
  2898. .Ex
  2899. #if _\^\^_STDC_\^\^_
  2900. #    define PROTO\^(x) x
  2901. #else
  2902. #    define PROTO\^(x) (\^)
  2903. #endif
  2904.  
  2905. extern char **ncopies PROTO((char *s, short times));
  2906. .Ee
  2907. Note that
  2908. .Ep PROTO
  2909. must be used with \fIdouble\fP parentheses.
  2910. .PP
  2911. In the end,
  2912. it may be best to write in only one style (e.g., with prototypes).
  2913. When a non-prototyped version is needed, it is generated using an
  2914. automatic conversion tool.
  2915. .NH 2
  2916. Pragmas
  2917. .PP
  2918. Pragmas
  2919. are used to introduce machine-dependent code in a controlled way.
  2920. Obviously, pragmas should be treated as machine dependencies.
  2921. Unfortunately, the syntax of \s-1ANSI\s+1 pragmas
  2922. makes it impossible to isolate them in machine-dependent headers.
  2923. .\"
  2924. .\" <side note>
  2925. .\" Because it is of the form ``#pragma'' instead of ``pragma(args)''.
  2926. .\" You can't put the #pragma in an include file, as it will get
  2927. .\" interpreted there.
  2928. .\"
  2929. .\" You are also prevented from embedding pragmas in macros.
  2930. .\"
  2931. .PP
  2932. Pragmas are of two classes.
  2933. .Ec Optimizations
  2934. may safely be ignored.
  2935. Pragmas that change the system behavior (``required pragmas'')
  2936. may not.
  2937. Required pragmas should be #ifdeffed so that compilation will abort if
  2938. no pragma is selected.
  2939. .PP
  2940. Two compilers may use a given pragma in two very different ways.
  2941. For instance, one compiler may use
  2942. .Ep haggis '' ``
  2943. to signal an optimization.
  2944. Another might use it to indicate that a given statement,
  2945. if reached, should terminate the program.
  2946. Thus, when pragmas are used,
  2947. they must always be enclosed in machine-dependent #ifdefs.
  2948. Pragmas must always be #ifdefed out for non-\s-1ANSI\s+1 compilers.
  2949. Be sure to indent the `#' character on the
  2950. .Ep #pragma ,
  2951. as older preprocessors will halt on it otherwise.
  2952. .Ex
  2953. #if defined(_\^\^_STDC_\^\^_) && defined(USE_HAGGIS_PRAGMA)
  2954.     #pragma (HAGGIS)
  2955. #endif
  2956. .Ee
  2957. .QP
  2958. ``\fIThe `#pragma' command is specified in the \s-1ANSI\s+1 standard to have an
  2959. arbitrary implementation-defined effect.
  2960. In the GNU C preprocessor, `#pragma' first attempts to run the game
  2961. `rogue'; if that fails, it tries to run the game `hack'; if that
  2962. fails, it tries to run GNU Emacs displaying the Tower of Hanoi; if
  2963. that fails, it reports a fatal error.
  2964. In any case, preprocessing does not continue.\fP''
  2965. .br
  2966. .ad r
  2967. \(em Manual for the GNU C preprocessor for GNU CC 1.34.
  2968. .br
  2969. .ad b
  2970. .\" NEED MORE STUFF!!
  2971. .NH
  2972. Special Considerations
  2973. .PP
  2974. This section contains some miscellaneous do's and don'ts.
  2975. .\"
  2976. .\" This should probably be either "dos and don'ts" or
  2977. .\" "do's and don't's", but neither looks quite right.
  2978. .\"
  2979. .IP \0\0\(bu
  2980. Don't change syntax via macro substitution.
  2981. It makes the program unintelligible to all but the perpetrator.
  2982. .IP \0\0\(bu
  2983. Don't use floating-point variables where discrete values are needed.
  2984. Using a
  2985. .Ec float
  2986. for a loop counter is a great way to shoot yourself in the foot.
  2987. Always test floating-point numbers as \fB<=\fP or \fB>=\fP,
  2988. never use an exact comparison (\fB=\^=\fP or \fB!=\fP\&).
  2989. .IP \0\0\(bu
  2990. Compilers have bugs.
  2991. Common trouble spots include structure assignment and bitfields.
  2992. You cannot generally predict which bugs a compiler has.
  2993. You \fIcould\fP write a program that avoids all constructs that are
  2994. known broken on all compilers.
  2995. You won't be able to write anything useful,
  2996. you might still encounter bugs,
  2997. and the compiler might get fixed in the meanwhile.
  2998. Thus, you should write ``around'' compiler bugs only when you are
  2999. \fIforced\fP to use a particular buggy compiler.
  3000. .IP \0\0\(bu
  3001. Do not rely on automatic beautifiers.
  3002. The main person who benefits from good program style is the
  3003. programmer him/herself,
  3004. and especially in the early design of handwritten algorithms
  3005. or pseudo-code.
  3006. Automatic beautifiers can only be applied to complete, syntactically
  3007. correct programs and hence are not available when the need for
  3008. attention to white space and indentation is greatest.
  3009. Programmers can do a better job of making clear
  3010. the complete visual layout of a function or file, with the normal
  3011. attention to detail of a careful programmer.
  3012. (In other words, some of the visual layout is dictated by intent
  3013. rather than syntax
  3014. and beautifiers cannot read minds.)
  3015. Sloppy programmers should learn to be careful programmers instead of
  3016. relying on a beautifier to make their code readable.
  3017. .\"
  3018. .\" Finally, beautifiers are nontrivial, can have bugs, and never do a
  3019. .\" perfect job.
  3020. .\" Also, beautifiers do things such as silently taking
  3021. .\" .Ep x=-1;
  3022. .\" to be old-style syntax for
  3023. .\" .Ep x -= 1;
  3024. .\" even though that might not be what is wanted, and
  3025. .\" such a conversion is \fIwrong\fP for ANSI-C input.
  3026. .\"
  3027. .IP \0\0\(bu
  3028. Accidental omission of the second
  3029. .Ep = '' ``
  3030. of the logical compare is a problem.
  3031. Use explicit tests.
  3032. Avoid assignment with implicit test.
  3033. .Ex
  3034. abool = bbool;
  3035. if (abool) { ...
  3036. .Ee
  3037. When embedded assignment \fIis\fP used, make the test explicit
  3038. so that it doesn't get ``fixed'' later.
  3039. .Ex
  3040. while ((abool = bbool) != FALSE) { ...
  3041. .Ee
  3042. .Ex
  3043. while (abool = bbool) { ...    /* VALUSED */
  3044. .Ee
  3045. .Ex
  3046. while (abool = bbool, abool) { ...
  3047. .Ee
  3048. .\"
  3049. .\" I happen to think the following is ugly, but it works if one of
  3050. .\" the values is a constant.
  3051. .\" The ``trick'' is to put a non-lvalue on the lhs.
  3052. .\" The compiler then barfs if an
  3053. .\" .Ep = '' ``
  3054. .\" is typed instead of the intended
  3055. .\" .Ep =\^= ''. ``
  3056. .\"
  3057. .\" .Ex
  3058. .\" if (2 == i) {...}
  3059. .\" .Ee
  3060. .\"
  3061. .IP \0\0\(bu
  3062. Explicitly comment
  3063. variables that are changed out of the normal control flow,
  3064. or other code that is likely to break during maintenance.
  3065. .IP \0\0\(bu
  3066. Modern compilers will put variables in registers automatically.
  3067. Use the
  3068. .Ec register
  3069. sparingly to indicate the variables that you think are most critical.
  3070. In extreme cases, mark the 2-4 most critical values as
  3071. .Ep register
  3072. and mark the rest as
  3073. .Ep REGISTER.
  3074. The latter can be #defined to
  3075. .Ep register
  3076. on those machines with many registers.
  3077. .NH
  3078. Lint
  3079. .PP
  3080. \fILint\fP is a C program checker [2][11] that examines C source files
  3081. to detect and report type incompatibilities, inconsistencies between
  3082. function definitions and calls,
  3083. potential program bugs, etc.
  3084. The use of \fIlint\fP on all programs is strongly recommended,
  3085. and it is expected that most projects will require programs to use
  3086. \fIlint\fP as part of the official acceptance procedure.
  3087. .PP
  3088. It should be noted that the best way to use \fIlint\fP is not as a
  3089. barrier that must be overcome before official acceptance of a program,
  3090. but rather as a tool to use during and after changes or additions to
  3091. the code.
  3092. \fILint\fP
  3093. can find obscure bugs and insure portability before problems occur.
  3094. Many messages from \fIlint\fP really do indicate something wrong.
  3095. One fun story is about is about a program that was missing
  3096. an argument to
  3097. .Ep fprintf '. `
  3098. .Ex
  3099. fprintf ("Usage: foo -bar <file>\\\en");
  3100. .Ee
  3101. The \fIauthor\fP never had a problem.
  3102. But the program dumped core every time an ordinary user made a mistake
  3103. on the command line.
  3104. Many versions of \fIlint\fP will catch this.
  3105. .PP
  3106. Most options are worth learning.
  3107. Some options may complain about legitimate things, but they will
  3108. also pick up many botches.
  3109. Note that \-p\*f
  3110. .FS
  3111. .IP \*F
  3112. Flag names may vary.
  3113. .FE
  3114. checks function-call type-consistency for only a subset
  3115. of library routines, so programs should be linted both with and
  3116. without \-p for the best ``coverage''.
  3117. .PP
  3118. \fILint\fP also recognizes several special comments in the code.
  3119. These comments both shut up \fIlint\fP when the code
  3120. otherwise makes it complain,
  3121. and also document special code.
  3122. .NH
  3123. Make
  3124. .PP
  3125. One other very useful tool is \fImake\fP [7].
  3126. During development,
  3127. \fImake\fP recompiles only those modules that have been changed
  3128. since the last time \fImake\fP was used.
  3129. It can be used to automate other tasks, as well.
  3130. Some common conventions include:
  3131. .TS
  3132. center;
  3133. r l.
  3134. all    \fIalways\fP makes all binaries
  3135. clean    remove all intermediate files
  3136. debug    make a test binary 'a.out' or 'debug'
  3137. depend    make transitive dependencies
  3138. install    install binaries, libraries, etc.
  3139. deinstall    back out of ``install''
  3140. mkcat    install the manual page(s)
  3141. lint    run lint
  3142. print/list    make a hard copy of all source files
  3143. shar    make a shar of all source files
  3144. spotless    make clean, use revision control to put away sources.
  3145.     Note: doesn't remove Makefile, although it is a source file
  3146. source    undo what spotless did
  3147. tags    run ctags, (using the -t flag is suggested)
  3148. rdist    distribute sources to other hosts
  3149. \fIfile.c\fP    check out the named file from revision control
  3150. .TE
  3151. In addition, command-line defines
  3152. can be given to define either Makefile values
  3153. (such as ``CFLAGS'')
  3154. or values in the program
  3155. (such as ``DEBUG'').
  3156. .NH
  3157. Project-Dependent Standards
  3158. .PP
  3159. Individual projects may wish to establish additional standards beyond
  3160. those given here.
  3161. The following issues are some of those that should be addressed by
  3162. each project program administration group.
  3163. .IP \0\0\(bu
  3164. What additional naming conventions should be followed?
  3165. In particular, systematic prefix conventions for functional grouping
  3166. of global data and also for structure or union member names can be
  3167. useful.
  3168. .IP \0\0\(bu
  3169. What kind of include file organization is appropriate for the
  3170. project's particular data hierarchy?
  3171. .IP \0\0\(bu
  3172. What procedures should be established for reviewing \fIlint\fP
  3173. complaints?
  3174. A tolerance level needs to be established in concert with the \fIlint\fP
  3175. options to prevent unimportant complaints from hiding complaints about
  3176. real bugs or inconsistencies.
  3177. .IP \0\0\(bu
  3178. If a project establishes its own archive libraries, it should plan on
  3179. supplying a lint library file [2] to the system administrators.
  3180. The lint library file allows \fIlint\fP to check for compatible use of
  3181. library functions.
  3182. .IP \0\0\(bu
  3183. What kind of revision control needs to be used?
  3184. .NH
  3185. Conclusion
  3186. .PP
  3187. A set of standards has been presented for C programming style.
  3188. Among the most important points are:
  3189. .IP \0\0\(bu
  3190. The proper use of white space and comments
  3191. so that the structure of the program is evident from
  3192. the layout of the code.
  3193. The use of simple expressions, statements, and functions
  3194. so that they may be understood easily.
  3195. .IP \0\0\(bu
  3196. To keep in mind that
  3197. you or someone else will likely be asked to modify code or make
  3198. it run on a different machine sometime in the future.
  3199. Craft code so that it is portable to obscure machines.
  3200. Localize optimizations since they are often confusing
  3201. and may be ``pessimizations'' on other machines.
  3202. .IP \0\0\(bu
  3203. Many style choices are arbitrary.
  3204. Having a style that is consistent
  3205. (particularly with group standards)
  3206. is more important than following absolute style rules.
  3207. Mixing styles is worse than using any single bad style.
  3208. .PP
  3209. As with any standard, it must be followed if it is to be useful.
  3210. If you have trouble following any of these standards
  3211. don't just ignore them.
  3212. Talk with your local guru,
  3213. or an experienced programmer at your institution.
  3214. .bp
  3215. .ce 1
  3216. \fBReferences\fP
  3217. .sp 2
  3218. .IP [1]
  3219. B.A. Tague, \fIC Language Portability\fP, Sept 22, 1977.
  3220. This document issued by department 8234 contains three memos by
  3221. R.C. Haight, A.L. Glasser, and T.L. Lyon dealing with style and
  3222. portability.
  3223. .IP [2]
  3224. S.C. Johnson, \fILint, a C Program Checker\fP,
  3225. \s-1USENIX\s+1
  3226. .UX
  3227. Supplementary Documents, November 1986.
  3228. .IP [3]
  3229. R.W. Mitze, \fIThe 3B/PDP-11 Swabbing Problem\fP, Memorandum for File,
  3230. 1273-770907.01MF,
  3231. September 14, 1977.
  3232. .IP [4]
  3233. R.A. Elliott and D.C. Pfeffer, \fI3B Processor Common Diagnostic
  3234. Standards- Version 1\fP,
  3235. Memorandum for File, 5514-780330.01MF, March 30, 1978.
  3236. .IP [5]
  3237. R.W. Mitze,
  3238. \fIAn Overview of C Compilation of
  3239. .UX
  3240. User Processes on the 3B\fP,
  3241. Memorandum for File, 5521-780329.02MF, March 29, 1978.
  3242. .IP [6]
  3243. B.W. Kernighan and D.M. Ritchie,
  3244. \fIThe C Programming Language\fP,
  3245. Prentice Hall 1978,
  3246. Second Ed. 1988, \s-1ISBN\s+1 0-13-110362-8.
  3247. .IP [7]
  3248. S.I. Feldman,
  3249. \fIMake \(em A Program for Maintaining Computer Programs\fP,
  3250. \s-1USENIX\s+1
  3251. .UX
  3252. Supplementary Documents, November 1986.
  3253. .IP [8]
  3254. Ian Darwin and Geoff Collyer,
  3255. \fICan't Happen or /* NOTREACHED */ or Real Programs Dump Core\fP,
  3256. \s-1USENIX\s+1 Association Winter Conference, Dallas 1985 Proceedings.
  3257. .IP [9]
  3258. Brian W. Kernighan and P. J. Plauger
  3259. \fIThe Elements of Programming Style\fP.
  3260. McGraw-Hill, 1974, Second Ed. 1978, \s-1ISBN\s+1 0-07-034-207-5.
  3261. .IP [10]
  3262. J. E. Lapin
  3263. \fIPortable C and U\s-1NIX\s+1 System Programming\fP,
  3264. Prentice Hall 1987,
  3265. \s-1ISBN\s+1 0-13-686494-5.
  3266. .IP [11]
  3267. Ian F. Darwin,
  3268. \fIChecking C Programs with lint\fP,
  3269. O'Reilly & Associates, 1989.
  3270. \s-1ISBN\s+1 0-937175-30-7.
  3271. .IP [12]
  3272. Andrew R. Koenig,
  3273. \fIC Traps and Pitfalls\fP,
  3274. Addison-Wesley, 1989.
  3275. \s-1ISBN\s+1 0-201-17928-8.
  3276. .\" .IP []
  3277. .\" Samuel P. Harbison and Guy L. Steele Jr.
  3278. .\" \fIC: A Reference Manual\fP
  3279. .\" 1984, 1987
  3280. .\" \s-1ISBN\s+1 is 0-13-109802-0
  3281. .\" .Ee
  3282. .\" .IP []
  3283. .\" Mark Horton
  3284. .\" \fIPortable C Software\fP
  3285. .\" Prentice-Hall, Englewood Cliffs NJ
  3286. .\" 1990
  3287. .\" \s-1ISBN\s+1 is 0-13-868050-7
  3288. .\" .Ee
  3289. .bp
  3290. \s+1
  3291. .ce
  3292. \fBThe Ten Commandments for C Programmers\fP
  3293. \s-1
  3294. .sp 2
  3295. .ce
  3296. \fIHenry Spencer\fP
  3297. .sp 2
  3298. .IP 1
  3299. Thou shalt run \fIlint\fP frequently and study its pronouncements with
  3300. care, for verily its perception and judgement oft exceed thine.
  3301. .IP 2
  3302. Thou shalt not follow the NULL pointer,
  3303. for chaos and madness await thee at its end.
  3304. .IP 3
  3305. Thou shalt cast all function arguments to the expected type
  3306. if they are not of that type already,
  3307. even when thou art convinced that this is unnecessary,
  3308. lest they take cruel vengeance upon thee when thou least expect it.
  3309. .IP 4
  3310. If thy header files fail to declare the return types
  3311. of thy library functions,
  3312. thou shalt declare them thyself with the most meticulous care,
  3313. lest grievous harm befall thy program.
  3314. .IP 5
  3315. Thou shalt check the array bounds of all strings (indeed, all arrays),
  3316. for surely where thou typest ``foo'' someone someday shall type
  3317. ``supercalifragilisticexpialidocious''.
  3318. .IP 6
  3319. If a function be advertised to return an error code in the event of
  3320. difficulties,
  3321. thou shalt check for that code, yea, even though the checks
  3322. triple the size of thy code and produce aches in thy typing fingers,
  3323. for if thou thinkest ``it cannot happen to me'',
  3324. the gods shall surely punish thee for thy arrogance.
  3325. .IP 7
  3326. Thou shalt study thy libraries and strive not to re-invent them
  3327. without cause,
  3328. that thy code may be short and readable and thy days pleasant and
  3329. productive.
  3330. .IP 8
  3331. Thou shalt make thy program's purpose and structure
  3332. clear to thy fellow man by using the
  3333. One True Brace Style,
  3334. even if thou likest it not,
  3335. for thy creativity is better used in solving problems than in creating
  3336. beautiful new impediments to understanding.
  3337. .IP 9
  3338. Thy external identifiers shall be unique in the first six characters,
  3339. though this harsh discipline be irksome and the years of its necessity
  3340. stretch before thee seemingly without end,
  3341. lest thou tear thy hair out and go mad on that fateful day when
  3342. thou desirest to make thy program run on an old system.
  3343. .IP 10
  3344. Thou shalt foreswear, renounce,
  3345. and abjure the vile heresy which claimeth
  3346. that ``All the world's a VAX'', and have no commerce with the
  3347. benighted heathens who cling to this barbarous belief,
  3348. that the days of thy program may be long even though the days of thy
  3349. current machine be short.
  3350.